GitHub Actions如何用于Golang_Golang CI配置示例

gitHub Actions 运行 go 测试需先用 actions/setup-go@v4 安装 Go（如 1.21.x），并用 hashFiles(‘**/go.sum’) 缓存 ~/go/pkg/mod；交叉编译应禁用 CGO 或使用对应 OS runner；go vet 和 staticcheck 需设 working-Directory 并升级工具版本。

github Actions 运行 Go 测试时找不到 go 命令？

默认 ubuntu runner 不预装 Go，直接写 go test 会报 /usr/bin/env: 'go': No such file or directory。必须显式安装 Go 环境。

推荐用 actions/setup-go@v4，它支持语义化版本匹配（如 1.21.x）和缓存 GOPATH：

steps:   - uses: actions/setup-go@v4     with:       go-version: '1.21.x'

• 避免硬写 1.21.0 —— 小版本更新后 workflow 会失败
• 若项目依赖 GO111MODULE=on（Go 1.16+ 默认开启），无需额外设置；但老项目建议显式加 env: { GO111MODULE: on }
• 不建议用 apt-get install golang：版本陈旧、无自动缓存、跨 runner 不一致

如何正确缓存 Go modules（go mod download）？

Go module 缓存能节省 30–60 秒构建时间，但误用 actions/cache 容易失效——关键在于缓存 key 必须包含 go.sum 的哈希，而非仅 go.mod。

官方推荐做法是用 gomod-cache action（底层仍调 actions/cache，但 key 构造更鲁棒）：

立即学习“go语言免费学习笔记（深入）”；

- uses: actions/setup-go@v4   with:     go-version: '1.21.x' - uses: actions/cache@v4   with:     path: ~/go/pkg/mod     key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}

• hashFiles('**/go.sum') 比 hashFiles('go.mod') 更可靠：go.sum 记录了所有间接依赖的校验和，变动即代表依赖树真实变化
• 路径必须写 ~/go/pkg/mod（Go 默认 GOPATH 下的模块缓存位置），不是 ${{ env.HOME }}/go/pkg/mod —— 后者在某些 runner 上解析为空
• 如果项目有多个 go.sum（如子模块），用 **/go.sum 覆盖全部

交叉编译 linux/macOS/windows 二进制时常见 panic

用 GOOS=windows GOARCH=amd64 go build 本地能跑，但在 GitHub Actions Ubuntu runner 上可能 panic：panic: runtime Error: invalid memory address or nil pointer dereference，尤其涉及 os/user 或信号处理。

根本原因是：部分 stdlib 在非宿主平台交叉编译时行为异常，且 CI runner 缺少真实系统上下文（如 user/group 数据库）。

• 优先用 buildmode=exe + 显式关闭 CGO：CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o dist/app.exe
• 若必须启用 CGO（如调用 C 库），则需在对应 OS 的 runner 上原生构建：用 strategy.matrix 分发到 ubuntu-latest / macos-latest / windows-latest
• 不要在 Linux runner 上交叉编译 macos 二进制——GOOS=darwin 无法生成可运行的 Mach-O，即使成功也会在 Mac 上报 Bad CPU type in executable

为什么 go vet 和 staticcheck 总提示 false positive？

go vet 在 CI 中常因未解析 vendor 或未设 GOPATH 报错 cannot find package；staticcheck 则容易对泛型代码或新语法（如 any 类型别名）误报。

解决关键是统一工作目录和模块根路径：

- name: Run go vet   run: go vet ./...   working-directory: ${{ github.workspace }}

• 务必加 working-directory，否则 go vet 可能在子目录执行，找不到顶层 go.mod
• 用 ./... 而非 .：前者递归检查所有子包，后者只检查当前包
• 若用 haya14busa/golangci-lint-action，确认其版本 >= v3.6.0，旧版不支持 Go 1.21 泛型推导
• 对误报项，宁可用 //lint:ignore ST1005 单行忽略，也别关全局检查——CI 是代码质量守门员，不是妥协工具

真正麻烦的从来不是写对一个 workflow，而是当 go.sum 变动、Go 小版本升级、或某次 staticcheck 规则收紧时，没人记得去翻两年前那个 .github/workflows/ci.yml 里埋着的 continue-on-error: true。