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 项目要保守一点。

参考资料

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。开发镜像和生产镜像最好分开，前者追求方便，后者追求可控和干净。把开发工具混进生产镜像，后面排安全扫描和镜像体积问题会比较烦。

参考资料

几个我觉得值得放进 Go 项目的开源工具

Thu, 18 Sep 2025 20:42:00 +0800

最近整理了一下几个 Go 项目里的开发工具。不是那种“必装清单”，更多是我在实际项目里会愿意留下来的东西。

有些工具刚开始看起来只是锦上添花，但项目稍微变大之后，它们能少掉不少重复劳动。

我现在选工具有个很朴素的标准：它最好能落到项目里的固定入口，而不是只存在于某个人的本机习惯里。比如 golangci-lint 能进 CI，gotestsum 能产出报告，GoReleaser 能跟 tag 发布绑定，这类工具的收益会比“我本地装了很好用”稳定得多。

Delve：调试 Go 程序还是绕不开它

Go 里当然可以一直靠日志定位问题，但遇到 goroutine、变量状态、条件分支比较绕的时候，还是调试器更直接。

Delve 是 Go 生态里比较常用的调试器，命令也不复杂：

1
2
3


dlv debug
dlv test ./...
dlv attach <pid>

我比较常用的是本地 dlv debug，还有偶尔调测试时用 dlv test。如果服务跑在容器里，远程调试要注意端口、权限和编译参数，不要默认把调试端口暴露到外网。

还有一个实际点：不要把 Delve 当成日志的替代品。它适合看“当时这个变量是什么”“这个分支为什么走到这里”，但线上问题还是要靠日志、指标和 trace 留证据。调试器解决的是复现后的观察问题，不解决线上证据不足。

Air：本地开发热重载

写 HTTP 服务时，反复 go run main.go 其实挺打断节奏。Air 做的事情很简单：监听文件变化，自动重新构建和启动。

一般项目根目录放一个 .air.toml 就够了：

1
2
3
4
5
6
7
8


root = "."
tmp_dir = "tmp"

[build]
cmd = "go build -o ./tmp/app ./cmd/server"
bin = "./tmp/app"
include_ext = ["go", "tpl", "tmpl", "html"]
exclude_dir = ["tmp", "vendor", "node_modules"]

这个工具不复杂，但能让本地开发体验舒服很多。

golangci-lint：把代码风格问题提前拦住

Go 自带 gofmt 已经解决了大部分格式问题，但项目里经常还会有未使用代码、错误处理不完整、复杂度过高、潜在 bug 之类的问题。

golangci-lint 的好处是可以把多个 linter 统一起来跑：

`1`	`golangci-lint run ./...`

我不太建议一上来把所有规则都打开。比较现实的做法是先从少量规则开始，比如 govet、staticcheck、errcheck，等团队习惯了再逐步加。否则第一次接入 CI，可能会刷出一大堆历史问题，最后没人愿意修。

sqlc：SQL 还是手写，但类型别手写

如果项目里 SQL 比较多，我会考虑用 sqlc。它的思路不是发明一个 ORM，而是让你继续写 SQL，然后从 SQL 生成类型安全的 Go 代码。

1
2
3
4


-- name: GetUser :one
SELECT id, name, email
FROM users
WHERE id = $1;

生成之后，在 Go 里调用时就有明确的参数和返回结构。这样比手动 Scan 一堆字段更稳，也比在业务代码里拼 SQL 更容易维护。

我个人更喜欢这种方式：复杂 SQL 仍然能看得见，类型检查交给工具。

它不适合所有项目。SQL 经常动态拼接、查询结构高度不稳定时，sqlc 反而会显得束手束脚。但如果核心查询比较稳定，尤其是后台服务、管理端、报表导出这类场景，它比手写一堆 Scan 靠谱。

Task：比 Makefile 更像配置文件

Makefile 很经典，但在跨平台场景下有时会遇到 shell 差异。Task 使用 Taskfile.yml，写起来更接近普通配置。

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


version: '3'

tasks:
 test:
 cmds:
 - go test ./...

 lint:
 cmds:
 - golangci-lint run ./...

 dev:
 cmds:
 - air

如果项目成员里有人用 Windows，有人用 macOS/Linux，Taskfile 的可读性会好一点。当然，如果项目已经有成熟 Makefile，也没必要为了换工具而换。

GoReleaser 和 gotestsum

GoReleaser 适合 CLI 工具或需要跨平台二进制发布的项目。比如同时构建 Linux、macOS、Windows，不同架构，再顺手生成压缩包、checksum、GitHub Release。

`1`	`goreleaser release --clean`

go test ./... 的输出在包多的时候不太好看，失败信息容易被淹没。gotestsum 的价值就是把测试结果整理得更适合人读，也方便 CI 消费。

1
2


gotestsum -- ./...
gotestsum --junitfile test.xml -- ./...

如果只能先放几个，我会按这个顺序来：

golangci-lint：最适合进 CI，收益稳定。
Delve：排查复杂问题时很实用。
gotestsum：测试包多之后很明显。
Air：本地服务开发体验提升明显。
sqlc：项目 SQL 多时再接入。
Task / Makefile：选一个就行，关键是命令入口统一。
GoReleaser：有发布二进制需求时再上。

工具不需要一次性堆满。我的经验是，先把“检查、测试、启动、发布”这几件事规范起来，项目后面会轻松不少。

我也不建议把这类文章看成工具排名。真正应该排优先级的是项目痛点：如果 CI 经常因为低级问题失败，先接 linter；如果本地启动麻烦，先接 Air 或 Task；如果发布靠手工压包，GoReleaser 的优先级就比调试器还高。