GitHub Actions 中 go test 失败主因是环境未对齐：需显式设置 GOOS/GOARCH、避免 go test ./ 扫描平台敏感测试、提前 go mod download 并缓存、用 -timeout 和 -race 分离控制、数据库测试禁用真实连接、所有命令在模块根目录执行。
GitHub Actions 里 go test 失败，90% 不是代码问题，而是环境没对齐——GOOS 没设、go test ./ 扫了不该扫的测试、go mod download 漏了或晚了。
GOOS 和 GOARCH 必须显式设置
GitHub 默认 runner 是 Linux，但 Go 不会自动按部署目标平台编译或运行测试。比如你有 //go:build windows 的测试文件，在 Linux CI 上被 go test ./ 扫到就会直接报错：找不到 syscall 或调用失败。
- 所有
go test步骤前加env:块：GOOS: linux（哪怕你本地是 macOS，CI 应以生产环境为准） - 交叉编译时也必须成对设：
GOOS=windows GOARCH=amd64 go build -o myapp.exe，漏一个就产出错平台二进制 - Windows 目标别忘了
.exe后缀，否则生成的文件在 Windows 上双击无响应
别用 go test ./ 扫全项目
这个命令会递归扫描所有子目录，包括带 //go:build darwin 或 //go:build cgo 的测试，而 CI 环境很可能不满足这些约束。
- 改用明确路径：
go test ./pkg/... ./cmd/...，避开 vendor、internal/testdata 或 platform-specific 目录 - 若需保留部分平台测试，用
-tags过滤：go test -tags=ci ./...，并在对应测试文件顶部写//go:build ci - HTTP 测试务必用
httptest.NewUnstartedServer+srv.Start+defer srv.Close，避免http.ListenAndServe占用端口导致后续测试失败
go mod download 必须提前执行
CI 容器是干净环境，没有缓存、没有 go.sum 锁定校验，依赖拉取失败或超时是高频原因。不提前下载，go test 过程中边跑边下，网络抖动就直接 timeout。
立即学习“go语言免费学习笔记（深入）”；
- 在
go test前加一步：run: go mod download - 配合
actions/cache@v4缓存$HOME/go/pkg/mod，key 建议含$(sha256sum go.sum | cut -c1-8)，避免go.sum变了却命中旧缓存 - 确保
go.sum已提交 Git——它不是“可选”，而是模块校验的唯一依据；不提交等于放弃供应链安全
测试超时和竞态必须单独控制
CI runner 对单 job 有硬性超时（GitHub 是 6 小时），但没人真等那么久。更常见的是测试卡在未关闭的 goroutine 或 DNS 查询上，表面看是挂起，实则是资源泄漏。
- 所有
go test命令加-timeout 60s，别信“本地 2 秒过”——CI 磁盘 IO、DNS 解析都更不可控 -
-race检测必须拆成独立 job，它会让测试变慢 3–5 倍，且和普通测试混跑可能掩盖真实 panic - 数据库测试禁用真实连接，改用
file::memory:SQLite 或testcontainers-go；若必须连外部服务，加-short跳过
最易被忽略的一点：所有构建步骤必须在模块根目录执行。CI 中误入子目录再跑 go build，会报 cannot find module providing package xxx——这不是依赖问题，是 Go 找不到 go.mod 上下文。每次 run: 前加一句 cd ${{ github.workspace }} 最稳妥。
