Go build cache 怎样区分源码变更与环境变更

我在 CI 上遇到过一种很容易误判的现象：源码没有改，第二次 go build ./... 却重新编译；也有人看到换了 GOCACHE 后第一次构建变慢，就认为 Go 没有识别环境。真正要分清的是两件事：GOCACHE 只是缓存存放位置，而缓存条目的键会综合源码、编译器、编译选项以及构建过程中会影响结果的环境输入。

排查时先不要清空缓存。先固定同一套工具链和构建参数，再用 GODEBUG=gocachehash=1 查看 Go 为缓存键收集了哪些输入。这样才能回答“到底什么变了”，而不是只得到一次代价很高的重建。

官方文档：https://pkg.go.dev/cmd/go

先确认：build cache 和 module cache 不是一回事

Go 有两类经常被混叫的缓存。构建缓存保存编译后的包和其他构建产物，默认位置可以用 go env GOCACHE 查看；模块缓存保存下载的依赖源码，位置通常由 GOMODCACHE 决定。改动依赖下载位置，不等于改动编译缓存；反过来也一样。

# 只查看与本次构建诊断直接相关的有效配置
go env GOCACHE GOMODCACHE GOOS GOARCH CGO_ENABLED GOFLAGS GOTOOLCHAIN

# 只清理构建产物；不要把它当成排查缓存键的第一步
go clean -cache

如果只是把 GOCACHE 指向一个全新的目录，第一次构建没有命中是正常的，因为目录里还没有可复用的条目。两台机器即使使用相同源码，也可能因为工具链、目标平台、编译标签或 cgo 条件不同而得到不同缓存键。

我实际会把缓存键拆成四组输入

为了避免“源码没改，所以产物必须一样”的直觉，我通常把一次构建理解成四组输入的组合：

• 源码与依赖：当前包的 Go 源文件、导入包以及模块解析结果发生变化，都会改变后续产物。
• 工具链：编译器和所用 Go 工具链变化，不能假设旧产物仍然等价。
• 编译选项：-tags、-gcflags、-ldflags、-trimpath 等会改变编译结果的参数应视为缓存键的一部分。
• 目标与构建环境：GOOS、GOARCH、架构特性、CGO_ENABLED 以及被 Go 工具读取的相关设置，会让同一份源码走不同构建路径。

这也是为什么“源码没改但缓存没命中”不一定是异常。比如从 GOOS=linux 切换到 GOOS=darwin，文件选择和编译目标已经变了；从 CGO_ENABLED=0 切换到 CGO_ENABLED=1，依赖的编译链也不同。缓存要保证的是相同输入可复用，而不是让不同输入强行共用产物。

用 gocachehash 找变化，不靠猜

缓存没有按预期命中时，可以只对一次构建打开哈希输入日志。输出会很多，适合保存到临时文件后按关键词比较。下面的命令不改变源码，只把构建缓存键的输入打印出来。

# 输出缓存键输入，便于比较两次构建的工具链和参数差异
GODEBUG=gocachehash=1 go build ./... > /tmp/go-build-cache-inputs.txt 2>&1

# 先看最可能造成分叉的环境和编译参数
rg 'GOOS|GOARCH|CGO_ENABLED|GOAMD64|GOFLAGS|gcflags|ldflags|trimpath|compile' /tmp/go-build-cache-inputs.txt

我会先比较两次日志中的目标平台、架构特性、cgo 状态和编译参数，再回头看具体包。若需要判断测试结果是否被复用，可以单独使用 GODEBUG=gocachetest=1；它针对的是成功的包测试结果，不应与构建产物缓存混为一谈。

这里有一个实用边界：GOCACHE 本身主要决定“去哪个目录找缓存”，换目录会造成冷启动；它不是用来声明“这份缓存来自哪个环境”的业务标签。更稳妥的做法是让 CI 任务固定工具链、目标平台和编译参数，并把缓存目录作为该构建环境的可复用存储。

反例：外部 C 库变了，Go 不一定知道

最容易被忽略的是 cgo。Go 官方文档明确说明，构建缓存能正确处理 Go 源码、编译器和编译选项等变化，但不会自动检测系统中被 cgo 导入的 C 库发生变化。于是可能出现“Go 输入看起来没变，链接到的外部库已经变了”的情况。

# 只有确认 cgo 依赖的系统 C 库发生变化时，才考虑强制重建
go clean -cache

# 也可以只对当前构建强制重新编译依赖包
go build -a ./...

这不是建议每次构建都清缓存。频繁清理会掩盖真正的环境漂移，还会让 CI 失去缓存收益。更好的办法是把 C 编译器、系统库版本和构建镜像一起固定；如果必须依赖宿主机库，就在构建记录中明确它们的版本变化和重建策略。

我给 CI 留下的判断清单

1. 先运行 go env GOCACHE GOOS GOARCH CGO_ENABLED GOFLAGS GOTOOLCHAIN，确认两次构建的关键环境是否相同。
2. 确认是否改变了 -tags、-gcflags、-ldflags 或 -trimpath，不要只看 Git 工作区。
3. 用一次 GODEBUG=gocachehash=1 go build ./... 保存输入，比较缓存键来源。
4. 如果启用了 cgo，再检查外部 C 库和编译器；确认它们变化后才使用 go clean -cache 或 go build -a。
5. 把构建镜像、Go 工具链、目标平台和关键参数固定下来，让“相同输入命中缓存”成为可重复条件。

我的结论是：Go build cache 不是只跟踪源码时间戳，而是在输入足够一致时复用构建结果。源码变化通常会被正确纳入；环境变化要看它是否真正参与 Go 的构建输入；宿主机外部 C 库则是明确的例外。先看缓存键，再决定是否清理，排查成本和构建稳定性都会更可控。

相关问题

换了 GOCACHE 为什么第一次构建很慢？

新目录没有旧条目，第一次构建是冷缓存。只要源码、工具链和编译参数保持一致，后续构建才有机会复用该目录中的结果。

go clean -cache 能解决所有缓存异常吗？

不能。它会删除构建缓存，但不会修复工具链漂移、编译参数不一致或外部 C 库变化造成的环境问题。清理前先用 gocachehash 找输入差异。