Go 测试为什么在本机过而在 CI 失败

Go 测试“本机通过、CI 失败”，通常不是 go test 随机失灵，而是两次测试看到的输入不一样：工具链版本、模块目录、GOOS/GOARCH、CGO_ENABLED、环境变量、工作目录、时区、文件权限、网络依赖或执行顺序，只要有一项不同，最终生成的测试二进制和运行条件就可能不同。

排查时先把本机与 CI 的信息采集方式统一，再关闭测试缓存重跑；确认是构建条件差异后，再检查运行时资源和并发顺序。这样比在 CI 里反复点“重新运行”更快收敛。

官方资料：https://pkg.go.dev/testing、https://pkg.go.dev/cmd/go、https://go.dev/ref/mod

先把本机和 CI 的触发条件对齐

go test 会把包与匹配 *_test.go 的文件一起编译，并为每个包执行独立的测试二进制。因此，第一步不是猜哪一行断言错了，而是让两边打印同一组上下文。

#!/usr/bin/env bash
set -euo pipefail

# 先记录工具链和目标平台，避免本机与 CI 实际使用的 Go 不同。
go version
go env GOROOT GOPATH GOOS GOARCH CGO_ENABLED GOPROXY

# 记录当前模块视图；./... 只代表当前工作目录下能看到的包。
go env GOMOD
go list -mod=readonly ./...

# 关闭测试缓存，并输出机器可解析的事件，便于 CI 保存失败上下文。
go test -count=1 -json ./...

这里的命令是诊断模板，不代表本文已经执行过某个项目。重点是把命令放到本机和 CI 的同一层级：如果 CI 在仓库子目录运行，模块根目录和 ./... 的包集合可能已经不同；如果 CI 禁用 CGO 或使用交叉编译目标，构建文件集合也可能不同。

先分清构建条件差异和运行时差异

这两类问题的修法不同。构建条件决定“哪些文件会进入测试二进制”，运行时差异决定“同一份二进制读到了什么资源”。可以按下面的顺序缩小范围：

Go 官方文档把 build constraint 定义为文件是否参与构建的条件，目标操作系统、架构、编译器和 CGO 都可能成为满足的标签。不要只在报错机器上改断言；先确认两边是否根本没有运行同一套文件。

package config_test

import (
    "os"
    "path/filepath"
    "testing"
)

func TestLoadFixture(t *testing.T) {
    // 用测试专属临时目录承载可写文件，避免依赖开发者本机的固定路径。
    dir := t.TempDir()
    fixture := filepath.Join(dir, "settings.txt")
    if err := os.WriteFile(fixture, []byte("mode=test\n"), 0o600); err != nil {
        t.Fatalf("写入测试夹具失败: %v", err)
    }

    // 测试应接收明确路径，而不是隐式依赖当前工作目录。
    if _, err := os.ReadFile(fixture); err != nil {
        t.Fatalf("读取测试夹具失败: %v", err)
    }
}

如果测试需要只读的静态样例，可把它放入包内的 testdata 目录，并在测试中明确计算路径；如果测试要写文件，不要把仓库目录当作临时工作区。网络、真实系统时间和共享端口也应被替换或隔离，否则本机资源越丰富，越容易掩盖 CI 的限制。

关闭缓存，把失败变成可定位的日志

Go 的测试缓存适合加速重复运行，但排查“刚改了代码却仍看到旧结果”时，先用 -count=1 明确要求重新执行。随后再按成本递增排查：先定位单个包或测试，再用竞态检测确认共享数据问题，最后检查随机顺序和资源竞争。

# 只重跑一个包，排除其他包的噪声。
go test -count=1 ./internal/config

# 用测试名缩小范围；正则只匹配目标测试及其子测试。
go test -count=1 -run 'TestLoadFixture' ./internal/config

# 共享内存或未同步写入可疑时，增加竞态检测。
go test -count=1 -race ./internal/config

# 保存结构化事件，CI 可以按 package、test 和 action 归档。
go test -count=1 -json ./internal/config

这些开关不是越多越好：-race 会改变运行成本，结构化日志也会增加输出量。诊断完成后，把稳定且必要的部分固化到门禁，把高成本检查放在单独的流水线阶段。

把检查固化成流水线门禁

自动化工作流的关键不是再加一条“运行测试”命令，而是规定触发条件、输入边界、失败产物和复盘入口。下面是一份可移植的 shell 门禁示例；具体 CI 平台只需要负责调用它并保存标准输出。

#!/usr/bin/env bash
set -euo pipefail

# 失败时仍让 CI 留下关键上下文，便于比较本机与构建机。
echo "工作目录: $(pwd)"
go version
go env GOOS GOARCH CGO_ENABLED GOMOD

# 只读依赖图，避免测试阶段悄悄改写 go.mod 或 go.sum。
go list -mod=readonly ./...

# 门禁默认禁用缓存；失败日志交给 CI 的 artifact 机制保存。
go test -count=1 -json ./... | tee test-results.json

如果失败只发生在 CI，先对比这份摘要，而不是先放宽断言。工具链不同就固定 CI 的 Go 版本；模块图不同就检查 go.mod、go.sum 和工作目录；构建条件不同就把目标平台与 CGO 策略写成明确配置；资源或顺序不同就让测试拥有自己的临时目录、端口、时钟和数据。

• 能稳定复现的失败：保留最小包、测试名和 -json 日志，修复输入边界。
• 只在并行运行失败：检查 t.Parallel、全局变量、临时文件名和端口分配。
• 只在不同平台失败：检查 build tag、路径分隔符、权限、换行符和 CGO。
• 只有偶发失败：保留失败时的环境摘要与随机顺序，再判断是否为时间或外部服务依赖。

两个容易混淆的问题

加上 -count=1 后仍然失败，说明是缓存问题吗？ 不一定。它只能排除测试缓存对这次运行的影响，不能修复工作目录、平台、依赖、权限、时间或并发共享状态。若失败仍在，优先比较两边的环境摘要。

本机和 CI 的 Go 版本一样，为什么还会失败？ Go 版本只是一个输入。GOOS、GOARCH、CGO_ENABLED、模块根目录、环境变量、文件系统、网络、时区和可用 CPU 都可能不同；把这些差异显式记录，才有机会得到稳定修复。

最终目标不是让 CI “偶尔重跑通过”，而是让每一次测试都拥有明确的工具链、模块、资源和输出契约。契约固定后，本机通过而 CI 失败就会从模糊现象变成可以逐项对比的工程问题。