Go GODEBUG gocacheverify 校验缓存一致性

遇到“本地能过、换一台机器结果不同”，先不要急着删除整个构建缓存。Go 提供的 GODEBUG=gocacheverify=1 会绕过已有缓存条目的直接复用，重新生成结果，并在写回时和原条目比较；一旦同一个 ActionID 对应的输出变化，命令会给出 cache verify failed，这比盲目执行 go clean -cache 更适合定位一致性问题。

官方资料：https://go.dev/doc/godebug

gocacheverify 到底校验什么

Go 的构建缓存用输入组成 ActionID，再关联编译产物的 OutputID 和文件大小。开启验证后，Get 会先按“未命中”处理，工具链继续执行编译或测试；随后 Put 会读取同一 ActionID 的旧记录，比较新旧输出。如果两者不同，Go 会报告旧 OutputID、新 OutputID 和对应的哈希线索。

因此它回答的是“相同缓存输入是否产生相同结果”，不是“缓存目录有没有垃圾文件”。验证模式会增加编译时间和磁盘读写，适合复现问题、诊断 CI 差异或比较工具链环境，不适合长期作为日常构建开关。

用一次性环境变量重建并观察失败点

把开关放在单条命令前面，避免污染当前 shell。项目有测试时先从目标包开始，再扩大到全仓库：

# 只对本次测试启用缓存一致性校验，结束后不会保留该设置
GODEBUG=gocacheverify=1 go test ./path/to/package

# 若目标是完整构建，可用同样方式检查所有包
GODEBUG=gocacheverify=1 go build ./...

出现 go: internal cache error: cache verify failed 时，先保留完整 stderr。日志里的 old 与 new 是比较线索，不代表可以直接把其中某个十六进制值当作文件内容。优先确认 Go 版本、编译器选项、环境变量、生成文件和工作目录是否一致，再判断是否是非确定性输出。

把 gocachehash 与清理操作放在正确位置

如果只知道“输出不同”还不够，可以临时加上 gocachehash=1，让 Go 打印参与内容哈希的输入。输出会很长，建议重定向到本地诊断文件，再围绕出现差异的包缩小范围：

# 同时记录输入哈希，便于对比两次构建的环境差异
GODEBUG=gocacheverify=1,gocachehash=1 go test ./path/to/package 2>cache-debug.log

# 只有确认缓存本身需要重新建立时，才清理构建缓存
go clean -cache

# 需要强制重编当前包及其依赖时，使用 -a；它和 verify 的目的不同
go build -a ./path/to/package

哪些情况不能只靠 gocacheverify 解决

Go 官方说明构建缓存会考虑 Go 源码、编译器和编译选项等输入，但 cgo 引入的 C 库变化不一定被缓存键覆盖。如果只更新了系统 C 库，先清理缓存或使用 -a 重建；不要把一次验证失败简单归因于 Go 缓存损坏。测试输出里若包含时间、随机数或外部服务响应，也可能天然不可复现，应该先隔离这些输入。

排查完成后恢复普通构建命令即可。不要把 gocacheverify=1 固定到生产环境或全局 CI 环境；它更像一次可重复性探针，发现差异后应继续追查生成过程、环境输入和依赖边界。

相关问题

gocacheverify 会删除已有缓存吗？

不会。它绕过缓存命中并在写回时比较旧记录；是否清理由 go clean -cache 单独决定。

为什么验证模式会让构建明显变慢？

因为每次都要重建并进行额外的旧新输出比较，不能享受普通缓存命中的速度。

gocachehash 能代替 gocacheverify 吗？

不能。前者帮助查看输入哈希，后者才负责重新生成并比较缓存输出，二者适合组合使用。