Go build cache 为什么没有缓存 cgo 编译结果

Go build cache 并不是一遇到 cgo 就停止缓存。排查“没有缓存 cgo 编译结果”时，应先分清包编译、外部 C 编译和最终链接。重复构建出现链接命令，不足以证明 cgo 包全部重新编译；CI 中缓存目录没有保存、构建输入发生变化或使用了 -a，也会让复用失效。

还有一个方向恰好相反：Go 官方文档说明，构建缓存不会自动检测通过 cgo 引用的系统 C 库内容变化。外部库更新后，问题可能是旧结果仍被复用，而不是没有缓存。需要按照实际症状选择处理方式，不能把清缓存当作所有慢构建问题的默认解法。

Go 官方地址：https://go.dev/

业务负载：先描述你期待复用哪一层

以容器化 CI 中的一个 cgo 服务为例，应用依赖本地 C 库，还要生成最终可执行文件。流水线可能同时使用 Go 模块下载缓存、Go 构建缓存、容器层缓存，以及外部 C 构建系统自己的缓存。它们的职责不同，恢复了其中一个不等于恢复了全部。

GOMODCACHE 主要避免重复下载模块；GOCACHE 存储 Go 构建输出；CMake 或 Make 等独立步骤的产物，则由相应工具与流水线管理。先写下究竟是哪条命令耗时、哪个步骤重复，才能决定该保存哪一个目录。这是架构选择示例，本文没有执行构建，也没有声称获得某个加速比例。

约束条件：保持可比较的工具链和输入

比较两次构建时，固定提交、Go 工具链、目标平台、cgo 开关及构建选项。记录实际 C 编译器和相关标志，避免两个看似相同的容器实际上装着不同工具链。下列命令供读者在自己的项目中排查，不会由文章生成任务执行。

# 只列出与本次构建有关的配置，不打印整套环境变量。
go version
go env GOCACHE GOMODCACHE GOOS GOARCH CGO_ENABLED CC CXX GOFLAGS
go env CGO_CFLAGS CGO_CPPFLAGS CGO_CXXFLAGS CGO_LDFLAGS

# 在相同目录、相同参数下连续构建，分别保留实际命令日志。
go build -x ./... 2> build-first.log
go build -x ./... 2> build-second.log

逐次确认退出状态成功后再比较日志。不要只比较两份文件的行数：关注是否对同一个包重复运行 cgo、C 编译器和 Go 编译器，还是只出现最终链接。构建脚本、代码生成和外部库安装也可能消耗时间，却不属于 Go 包缓存命中本身。

检查 GOFLAGS 与 CI 配置是否夹带 -a。该选项强制重建，适合明确需要失效的场景，但每轮都使用会主动放弃正常缓存收益。CI 结束后还应保存实际 go env GOCACHE 对应目录，下一轮在构建前恢复它；缓存路径变更、权限问题和恢复时机错误，都可能让“已开启缓存”的配置没有实际效果。

方案对比：持久化缓存还是固定构建镜像

持久化和固定镜像通常可以同时使用。对于依赖系统原生库的项目，把原生依赖版本或构建镜像摘要放进 CI 缓存分组中，能帮助明确什么时候不再恢复旧缓存。这是流水线层面的失效策略，不意味着 Go 内部会自动追踪系统库的每个字节。

推荐架构：分别管理环境、缓存和原生产物

一种便于维护的组织方式，是把构建镜像作为工具链与系统库版本的边界，GOCACHE 作为可丢弃的性能数据，外部 C 产物按自己的构建规则生成和恢复，最终发布物单独归档。缓存丢失应当影响速度，不能让构建缺少必要的源码、头文件或库。

同一缓存目录可以服务多个 Go 构建动作，但 CI 平台的外层缓存键仍要考虑工作负载，避免巨大且低价值的缓存传输抵消收益。不要只用 go.sum 代表全部原生输入：它描述 Go 模块依赖，不负责记录系统软件包更新。

风险点：外部 C 库更新反而可能没有触发重建

当你更新系统 C 库却仍得到旧行为，官方给出的处理是显式清理缓存，或用 -a 重建依赖该库的包。选择其中一种受控操作即可；不要为了排查“构建慢”，在每轮开头连续执行清缓存和强制重建。

# 仅在已确认原生库更新、需要强制重建时采用。
# 请把 ./... 替换为项目需要重建的包范围。
go build -a ./...

若选择 go clean -cache，它清理的是构建缓存，不是只清理某个 cgo 包；下一轮其他构建也会变冷。动态链接库在运行时如何加载还是另一层问题，重建成功不保证目标机器加载的是你期望的库版本，应按部署环境约定管理原生依赖。

需要进一步理解缓存输入时，可以临时启用 gocachehash。输出可能很多，适合聚焦一个包，不适合作为每次生产构建的默认日志。

# 在相同构建条件下观察缓存键的输入；日志可能含本地路径。
GODEBUG=gocachehash=1 go build ./... 2> cache-inputs.log

比较的是两次输入差异，不是看到哈希文字就认定命中或未命中。对外分享日志前删去敏感路径和编译标志中的私密内容。不要把 gocachetest 当作包编译缓存诊断，它关注的是测试结果缓存；也不要用 go clean -testcache 期待清掉构建产物。

落地清单：先证明重复了什么，再选择动作

先确认两轮构建成功且条件一致，再根据 -x 日志找到重复动作；确认 GOCACHE 确实跨任务保存，并移除常态 -a；如果外部 C 构建独立发生，单独管理它；原生库更新时使用明确版本化或受控失效策略。这样既能避免无意义重编，也能减少错误复用。

cgo 工具链还受平台、编译器和本地库可用性约束。缓存不能替代安装依赖，也不能让缺少交叉 C 编译器的环境自动完成跨平台构建。先让干净环境能够正确构建，再讨论缓存带来的成本改善。

相关问题

第二次还有链接命令，是否表示缓存完全没用？

不能据此判断。要按包编译、原生编译和最终链接分别观察；一次链接不等于所有依赖都重新编译。

只缓存模块下载目录够吗？

它能减少重复下载，但不能等同于持久化 GOCACHE，也不包含独立 C 构建系统的全部产物。

更新系统库后，是不是只要再运行一次普通 build？

不能假设缓存会检测所有系统 C 库变化。按官方文档执行受控强制重建或清理，并在流水线中明确原生依赖版本。

参考：Go 构建与测试缓存、cgo 工具文档。