Go项目GitHub Actions CI需三步：选对runner、正确设GOPATH/GOROOT、避免本地缓存干扰；常见“cannot find module”因未启用Go modules或工作目录错误，须确保go.mod存在、checkout后不误cd、显式设GOPROXY；缓存go.mod用actions/cache并以go.sum哈希为key；race测试失败多因内存不足，应限范围使用并注意cgo限制。

Go 项目用 GitHub Actions 跑 CI，核心就三件事：选对 runner、正确设置 GOPATH 和 GOROOT、避免本地缓存干扰远程构建。

为什么 go build 在 Actions 里报 “cannot find module”

这是最常见问题，本质是没启用 Go modules 或工作目录不对。GitHub Actions 默认不会自动 cd 到你期望的模块根目录，且旧版 Ubuntu runner（如 ubuntu-18.04）默认 GOPROXY 为空，拉包失败也不报明确错误。

• 确保项目根目录下有 go.mod 文件，且 actions/checkout@v4 后没有额外 cd 到子目录
• 显式设置环境变量：GOPROXY=https://proxy.golang.org,direct（国内可换为 https://goproxy.cn）
• Go 1.16+ 默认启用 modules，但若项目在子目录（如 cmd/myapp），需在 run 步骤中加 cd ../.. 或改用 working-directory 参数

如何复用 go mod download 缓存加速构建

Go modules 下载的包体积大、重复拉取慢，直接靠 actions/cache@v4 缓存 $GOPATH/pkg/mod 最有效，但要注意路径和 key 的一致性。

Golang Spf13 Viper

Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。

下载

• 先用 go env GOPATH 确认实际路径（Actions 中通常是 /home/runner/go）
• 缓存 key 建议包含 go.sum hash：${{ hashFiles('**/go.sum') }}，比单纯用 Go 版本更精准
• 必须在 go mod download 之前 restore，在它之后 save，顺序错会导致缓存写入失败
• 示例片段：

  steps:
    - uses: actions/cache@v4
      with:
        path: /home/runner/go/pkg/mod
        key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
    - run: go mod download

测试时为何 go test -race 报 “failed to create race detector metadata”

这是 Go race detector 对内存和内核参数敏感导致的，尤其在 GitHub-hosted runner 的容器环境中容易触发。不是代码问题，而是资源限制。

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

• race 检测本身会显著增加内存占用（常翻 2–3 倍），ubuntu-latest runner 默认只有 7GB 内存，大型项目易 OOM
• 避免在所有 job 中无差别启用：-race 只应在专用 test job 中使用，且配合 -short 或指定包（如 ./... -run=TestUnit）缩小范围
• 若仍失败，可临时降级到 ubuntu-22.04（内存更大）或改用 actions/runner 自建节点
• 注意：race 不支持 cgo 混合项目，若用了 net 或 os/exec 等含 cgo 的包，需加 CGO_ENABLED=0

真正麻烦的不是写 YAML，而是本地 go test 过了，CI 却卡在 go list -mod=readonly —— 那大概率是 go.work 文件没提交，或者 replace 指向了本地绝对路径。这类问题不会报错，只会静默跳过依赖，直到 runtime panic 才暴露。