Tools on DK Blog

GoReleaser：给 Go CLI 做跨平台发布

Thu, 07 May 2026 21:38:00 +0800

Go 写 CLI 有个很舒服的地方：交叉编译比较简单。

1
2
3


GOOS=linux GOARCH=amd64 go build -o dist/app-linux-amd64
GOOS=darwin GOARCH=arm64 go build -o dist/app-darwin-arm64
GOOS=windows GOARCH=amd64 go build -o dist/app-windows-amd64.exe

命令本身不难，但真到发布的时候，事情会变多：多平台构建、文件命名、压缩包、checksum、GitHub Release、changelog、tag 和版本号。

这些东西手写脚本当然也能做，但维护起来不太舒服。GoReleaser 适合解决的就是这类问题：把 Go 项目的发布流程配置化。

我对 GoReleaser 的理解不是“它帮我编译 Go 程序”，而是“它帮我把发布动作固定下来”。一次发布最容易出错的地方往往不是 go build，而是漏传一个平台、checksum 忘了生成、tag 和 changelog 对不上、Release 里残留了上一次的产物。

初始化配置

本地可以直接安装：

1
2
3


go install github.com/goreleaser/goreleaser/v2@latest

goreleaser --version

在 Go CLI 项目根目录执行：

`1`	`goreleaser init`

它会生成 .goreleaser.yaml。刚开始不要急着把配置写复杂。一个简单 CLI 项目，我通常先这样配：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


version: 2

project_name: mycli

before:
 hooks:
 - go mod tidy

builds:
 - id: mycli
 main: ./cmd/mycli
 binary: mycli
 env:
 - CGO_ENABLED=0
 goos:
 - linux
 - darwin
 - windows
 goarch:
 - amd64
 - arm64

archives:
 - id: mycli
 formats:
 - tar.gz
 format_overrides:
 - goos: windows
 formats:
 - zip
 name_template: >-
 {{ .ProjectName }}_
 {{ .Version }}_
 {{ .Os }}_
 {{ .Arch }}

checksum:
 name_template: "checksums.txt"

snapshot:
 version_template: "{{ incpatch .Version }}-next"

changelog:
 sort: asc

main 是入口路径。很多 CLI 项目入口会放在 cmd/mycli，这里不要写错。

CGO_ENABLED=0 是为了尽量减少对系统动态库的依赖。不是所有项目都适合关 CGO，比如依赖 SQLite CGO 驱动的时候就要注意。

本地先跑 snapshot

第一次配 GoReleaser，不建议直接发布。可以先跑 snapshot：

`1`	`goreleaser release --snapshot --clean`

这个命令不会创建正式 GitHub Release，更适合本地检查构建产物。

如果这里都构建不过，先别放到 CI 里折腾。大部分问题本地就能看出来，比如入口路径不对、CGO 配置不对、包名冲突、依赖下载失败。

我会把 snapshot 当成发布前演练。它的价值是让你在没有污染 GitHub Release 的情况下，先看到最终产物大概长什么样。

给 CLI 注入版本号

CLI 工具一般会有一个 version 命令，至少要能看到当前版本。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


package main

import "fmt"

var (
 version = "dev"
 commit = "none"
 date = "unknown"
)

func main() {
 fmt.Printf("version=%s commit=%s date=%s\n", version, commit, date)
}

然后在 GoReleaser 里通过 ldflags 注入：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


builds:
 - id: mycli
 main: ./cmd/mycli
 binary: mycli
 env:
 - CGO_ENABLED=0
 ldflags:
 - -s -w
 - -X main.version={{ .Version }}
 - -X main.commit={{ .Commit }}
 - -X main.date={{ .Date }}

这里有个细节：-X main.version=... 的包路径要和变量所在包匹配。如果变量不在 main 包，就不能照抄这个路径。

这个坑很常见。很多项目会把版本变量放到 internal/version，这时 -X main.version=... 看起来配置了，实际上没有注入成功。发布前一定要跑一下二进制的 version 命令，而不是只看构建成功。

接入 GitHub Actions

正式发布可以用 GitHub Actions 触发 tag。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


name: release

on:
 push:
 tags:
 - "v*"

permissions:
 contents: write

jobs:
 goreleaser:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout
 uses: actions/checkout@v4
 with:
 fetch-depth: 0

 - name: Set up Go
 uses: actions/setup-go@v5
 with:
 go-version: stable

 - name: Run GoReleaser
 uses: goreleaser/goreleaser-action@v6
 with:
 distribution: goreleaser
 version: latest
 args: release --clean
 env:
 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

fetch-depth: 0 很重要。GoReleaser 需要读取 tag、commit 历史来生成版本和 changelog，浅克隆有时候会导致信息不完整。

触发条件是 tag：

1
2


git tag v0.1.0
git push origin v0.1.0

发布前我一般会固定跑：

1
2
3


go test ./...
goreleaser check
goreleaser release --snapshot --clean

GoReleaser 帮我省掉的不是一条 go build 命令，而是发布时那一串容易遗漏的小事：多平台构建、压缩包、checksum、Release 上传、版本号和 changelog。

如果项目依赖 CGO，我会先只发布自己能验证的平台。不要为了看起来完整，一上来就把 Linux、macOS、Windows、amd64、arm64 全打开。纯 Go 项目可以激进一点，CGO 项目要保守一点。

参考资料

macOS 使用 Privoxy 将 SOCKS5 转 HTTP 代理（完整步骤）

Thu, 05 Mar 2026 10:00:00 +0800

macOS 使用 Privoxy 将 SOCKS5 代理转换为 HTTP 代理

很多代理工具（如 Clash、V2Ray、Shadowsocks）提供的是 SOCKS5 代理。但有些开发工具（例如某些 CLI、构建工具、老软件）只支持 HTTP/HTTPS 代理。

这时可以使用 Privoxy 作为中间层，将 SOCKS5 代理转换为 HTTP 代理。

一、整体架构

代理请求流程如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


应用程序（只支持 HTTP Proxy）
 |
 v
HTTP Proxy
Privoxy (127.0.0.1:7890)
 |
 v
SOCKS5 Proxy
127.0.0.1:13659
 |
 v
代理客户端（Clash / V2Ray / Shadowsocks）
 |
 v
互联网

简单理解：HTTP Proxy -> Privoxy -> SOCKS5 Proxy。

二、安装 Privoxy

macOS 推荐使用 Homebrew：

`1`	`brew install privoxy`

安装后配置文件通常位于：

`1`	`/opt/homebrew/etc/privoxy/config`

三、修改 Privoxy 配置

打开配置文件：

`1`	`vim /opt/homebrew/etc/privoxy/config`

在文件末尾添加：

1
2


listen-address 127.0.0.1:7890
forward-socks5 / 127.0.0.1:13659 .

配置说明

listen-address 127.0.0.1:7890

Privoxy 在本地 7890 端口提供 HTTP 代理服务。

forward-socks5 / 127.0.0.1:13659 .

/：匹配所有请求。
127.0.0.1:13659：上游 SOCKS5 代理地址。
.：不指定额外 DNS 服务器。

四、启动 Privoxy

`1`	`brew services start privoxy`

常用管理命令：

1
2
3


brew services stop privoxy
brew services restart privoxy
brew services list | grep privoxy

五、配置终端代理（可选）

临时生效：

1
2


export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

长期生效（写入 ~/.zshrc）：

1
2
3


echo 'export HTTP_PROXY="http://127.0.0.1:7890"' >> ~/.zshrc
echo 'export HTTPS_PROXY="http://127.0.0.1:7890"' >> ~/.zshrc
source ~/.zshrc

六、测试代理是否生效

`1`	`curl -x http://127.0.0.1:7890 ipinfo.io`

如果返回的 IP 为代理出口 IP，说明配置成功。

七、常见使用场景

Git 代理：

1
2


git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

Docker 代理（~/.docker/config.json）：

1
2
3
4
5
6
7
8


{
 "proxies": {
 "default": {
 "httpProxy": "http://127.0.0.1:7890",
 "httpsProxy": "http://127.0.0.1:7890"
 }
 }
}

pip 代理：

`1`	`pip install -i https://pypi.org/simple package_name --proxy http://127.0.0.1:7890`

八、常见问题

端口冲突

如果 7890 被占用，可改为其他端口，例如：

`1`	`listen-address 127.0.0.1:8888`

并同步更新环境变量与工具配置。

查看端口占用

`1`	`lsof -i :7890`

九、总结

通过 Privoxy 可以把 SOCKS5 代理转换为 HTTP 代理，解决“工具只支持 HTTP 代理”的兼容问题。

落地步骤很简单：

安装 Privoxy。
修改 config 增加 listen-address 与 forward-socks5。
启动服务并验证。
按需配置系统或工具级 HTTP 代理。

Air：Go 本地开发热重载工具使用记录

Thu, 18 Dec 2025 22:16:00 +0800

以前写 Go 服务，本地调试基本就是：

`1`	`go run main.go`

改完代码以后手动停掉，再重新跑一遍。

项目小的时候还行，接口多了以后就有点烦。尤其是调 Web API、后台任务、配置解析这些东西，频繁重启很影响节奏。后来我在几个 Go 项目里用了 Air，主要目的就一个：文件变化以后自动重新编译和启动。

Air 本身没有什么复杂概念，它做的事情很直接：

监听文件变化。
重新执行构建命令。
杀掉旧进程。
启动新进程。

我后来发现，Air 最值钱的地方不是“热重载”这三个字，而是让本地启动变成一种项目约定。只要 .air.toml 写在仓库里，新人不需要问入口在哪、构建产物放哪、改配置会不会重启。

安装和初始化

官方 README 里给的方式比较多，我一般直接用 go install：

`1`	`go install github.com/air-verse/air@latest`

装完以后确认一下：

air -v

如果命令找不到，大概率是 $GOPATH/bin 没有放进 PATH。Windows 下可以看一下：

1

go env GOPATH

在项目根目录执行：

`1`	`air init`

它会生成一个 .air.toml 文件。这个文件就是 Air 的主要配置。

我常用的配置

我一般不会直接用默认配置跑所有项目，至少会改这几个地方：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


root = "."
tmp_dir = "tmp"

[build]
cmd = "go build -o ./tmp/server ./cmd/server"
bin = "./tmp/server"
include_ext = ["go", "yaml", "yml", "toml", "tmpl", "html"]
exclude_dir = ["tmp", "vendor", ".git", "node_modules"]
exclude_regex = ["_test.go"]
delay = 800
stop_on_error = true
send_interrupt = true
kill_delay = "500ms"

[log]
time = true

cmd 是构建命令，不一定非得是 go build 当前目录。比如项目入口在 cmd/server，就写成：

1

cmd = "go build -o ./tmp/app ./cmd/server"

tmp_dir 建议单独放一个目录，不要把构建产物扔在项目根目录。这个目录后面也要加到 .gitignore：

tmp/

include_ext 控制监听哪些后缀。如果只是 Go 服务，go 就够了。如果接口模板、页面模板也在项目里，可以加上 html、tmpl、tpl。

exclude_dir 也很关键。像 tmp、vendor、testdata 这种目录没必要监听，不排除的话容易出现重复构建或者无意义重启。

如果团队里有人在 Windows 上开发，我会特别确认路径和进程退出行为。Air 本身跨平台，但你的服务是否能正确响应中断、端口是否及时释放，才是本地体验的关键。

启动和环境变量

配置好以后，项目根目录执行：

air

之后改 Go 文件，Air 会自动重新编译。

有些服务启动时依赖环境变量，比如配置文件路径、运行环境、端口。

Linux/macOS 可以这样：

1

APP_ENV=local CONFIG=./config/local.yaml air

Windows PowerShell 可以这样：

1
2
3


$env:APP_ENV="local"
$env:CONFIG="./config/local.yaml"
air

Air 不负责替你管理配置，它只是负责重新构建和重启进程。

和 Docker 开发环境一起用

如果 Go 服务跑在容器里，也可以在容器里装 Air。更常见的做法是写一个开发用 docker-compose：

1
2
3
4
5
6
7
8
9


services:
 api:
 image: golang:1.24
 working_dir: /app
 volumes:
 - .:/app
 command: air
 ports:
 - "8080:8080"

这种方式适合团队统一开发环境，但也有代价：Windows/macOS 通过挂载目录时，有时会比直接在宿主机跑慢一点。

几个踩过的小问题

第一个问题是端口占用。如果服务退出不干净，新进程启动时会报端口被占用。Windows 下可以查：

1

netstat -ano | findstr :8080

第二个问题是构建产物被监听。如果 tmp 没有放进 exclude_dir，构建生成文件后又触发一次文件变化，可能会造成重复构建。

第三个问题是入口路径写错。有些项目入口不在根目录，而是在 cmd/api 或 cmd/server，那 .air.toml 里的 cmd 就不要写成 go build -o ./tmp/app .。

Air 适合自动重启服务，但它不是测试框架。单元测试、集成测试还是应该用 go test、gotestsum 或 CI 单独处理。

我也不会在生产镜像里装 Air。开发镜像和生产镜像最好分开，前者追求方便，后者追求可控和干净。把开发工具混进生产镜像，后面排安全扫描和镜像体积问题会比较烦。