Go build cache 怎样排查环境变量变化后仍复用旧结果

改了一个环境变量，重新执行 go build，产物却和之前一样，很多人第一反应是“Go 把旧结果缓存住了”。这个判断只对了一半：Go 构建缓存不是按“当前 shell 是否发生过变化”来失效，而是根据构建输入决定能不能复用。运行时才读取的变量、没有声明给构建系统的外部生成器，甚至 cgo 依赖的 C 库，都可能让你看到“环境变了，结果没变”。

先把“环境变量变了”拆成三类

排障时先不要执行清理命令。把变化的变量和它的读取位置记下来，通常能分出下面三类：

症状一：改了 APP_MODE，二进制行为却没有变化

看一个最容易误判的例子：

package main

import (
    "fmt"
    "os"
)

func main() {
    // 这个变量在程序启动后才读取，编译阶段没有把它当成源码输入。
    mode := os.Getenv("APP_MODE")
    if mode == "" {
        mode = "default"
    }
    fmt.Println("运行模式:", mode)
}

如果只是改了 APP_MODE，正确的检查方式是用不同环境启动同一个二进制，而不是期待 go build 必须重新编译。要把配置固化进产物，应该改成生成代码、链接参数或明确的构建标签，并把生成动作纳入可追踪的构建流程。

# 运行时变量变化只影响启动行为，不要求重新编译
APP_MODE=staging ./demo
APP_MODE=production ./demo

# 只有构建选择发生变化时，才把它写进构建命令并比较产物
go build -tags=production -o demo-prod .

这里的重点是“变量在哪里被读取”。同一个名字，如果被代码在运行时读取，和被生成器在编译前读取，缓存语义完全不同。

症状二：生成器或 cgo 变了，Go 仍然复用旧对象

Go 官方文档明确说明，构建缓存会正确考虑 Go 源码、编译器、编译选项等变化；但它不会检测 cgo 导入的 C 库变化。如果本机的 C 库已经更新，缓存中的 Go 包仍可能对应旧的 C 依赖，这时需要显式清理缓存，或者使用 -a 强制重建依赖包。

类似问题也会出现在“先运行脚本生成文件，再执行 go build”的流程里。如果生成文件没有进入 Go 包的依赖关系，或者构建系统没有把生成器版本、输入文件和输出文件关联起来，Go 命令就没有足够信息判断缓存应该失效。

# 查看当前 Go 构建缓存目录，先确认自己清理的是哪一处
go env GOCACHE

# cgo 依赖的外部库发生变化时，显式删除构建缓存
go clean -cache

# 只在需要完整重建时使用，避免把它当作日常默认命令
go build -a ./...

go clean -cache 会删除构建缓存；它不是修复依赖声明的替代品。若每次都靠清理命令才能得到正确产物，应该回头检查生成文件、C 库版本和构建脚本是否已经成为可追踪输入。

用 gocachehash 看到缓存键到底读了什么

当你不能确定某个变量是否进入构建判断时，优先查看缓存键输入，而不是猜测。官方提供了三个很有针对性的调试开关：

• GODEBUG=gocachehash=1：打印构造内容哈希时使用的输入，输出会很多，适合定位变量、文件或编译参数是否被读到。
• GODEBUG=gocacheverify=1：绕过已有缓存条目重新构建，并检查结果是否与旧条目一致。
• GODEBUG=gocachetest=1：打印测试结果是否复用缓存的判断细节。

# 观察构建缓存键的输入；输出较多，建议重定向到临时日志
GODEBUG=gocachehash=1 go build ./... 2> cache-hash.log

# 用于核对缓存结果是否与重新构建一致
GODEBUG=gocacheverify=1 go build ./...

# 测试缓存单独排查，不要把它和构建缓存混为一谈
GODEBUG=gocachetest=1 go test ./...

如果只是想让测试强制再跑一次，使用 -count=1 比清理整个构建缓存更精确：

# 禁用本次测试结果复用，但不删除所有构建缓存
go test -count=1 ./...

一轮排查应该留下什么记录

建议把一次“环境变了但结果没变”的排查写成四行记录，之后复现会快很多：

1. 记录变量的读取时机：编译期生成器、编译参数，还是程序启动后的 os.Getenv。
2. 记录目标平台和构建选择：go env GOOS GOARCH、构建标签、编译器和重要的 -gcflags/-ldflags。
3. 用 GODEBUG=gocachehash=1 或 gocacheverify=1 得到缓存判断线索。
4. 只有确认外部依赖没有被缓存键覆盖时，才使用 go clean -cache 或 go build -a，并把原因补回构建脚本。

这样做的价值是把“清缓存后好像好了”变成可解释的结论：到底是缓存键输入改变了、外部依赖没有声明，还是本来就只是运行时配置变化。

常见问题

改了 GOOS 或 GOARCH，还需要手动清理缓存吗？

通常先不需要。它们是构建目标的重要线索，应该直接出现在构建环境和命令记录中；若仍怀疑缓存异常，再用 gocachehash 或 gocacheverify 看输入。

为什么改了 cgo 使用的系统库却没有重新编译？

Go 的构建缓存不会检测 cgo 导入的 C 库变化。确认库已经更新后，可以清理缓存或使用 -a，更重要的是把系统库版本纳入可重复构建环境。

go clean -testcache 能解决构建产物旧吗？

不能。go clean -testcache 清理的是成功测试结果；构建对象使用 go clean -cache，两者不要混用。

每次都加 -a 是否最稳妥？

它能强制重建，但会牺牲缓存带来的速度。更好的做法是先确定真正没有进入构建输入的依赖，再修正生成流程或依赖声明，最后只在必要场景使用 -a。

所以，环境变量变化后结果没变，第一步不是清空所有缓存，而是确认变量的读取时机和它是否真的参与构建。把运行时配置、构建选择、生成器输入和 cgo 外部库分开记录，再用 Go 自带的缓存诊断开关定位，通常就能找到“旧结果”到底来自正确复用，还是来自未被声明的外部变化。