Go go.sum 校验记录的提交策略

在 Go Modules 项目里，go.sum 通常应该和 go.mod 一起提交。它记录模块版本对应的校验和，让后续开发机、构建机和 CI 在重新下载依赖时有可比对的依据；它不是临时缓存，也不应该靠手工删行来“整理”。

官方参考：https://go.dev/ref/mod

实用策略是：由 Go 命令生成和维护 go.sum，把与依赖变更对应的 diff 纳入评审；公开依赖正常提交校验记录，私有依赖先配置好环境变量，CI 再用只读模式阻止构建过程偷偷改文件。

先把 go.mod 和 go.sum 的职责分开

go.mod 描述模块路径、Go 版本和依赖版本，是依赖图的声明入口；go.sum 保存下载过的模块版本及其内容或 go.mod 文件的校验记录。两者的行数不需要一一对应：某个依赖的模块包和它自己的 go.mod 可能各自有记录，也可能因为构建路径不同而出现间接依赖的校验行。

因此，看到 go.sum 增加几行时，先问“哪一次依赖解析触发了它”，不要问“能不能把文件压缩到最短”。只要依赖图仍然需要这些记录，删除它们并不会让项目更干净，反而可能让离线构建或受限网络环境在下一次解析时重新写文件。

用 Go 命令生成校验记录

新增或升级依赖时，让 go get 修改依赖声明，再用 go mod tidy 按当前源码和测试依赖整理模块文件。下面的命令只展示常用顺序，版本号请替换成项目实际需要的版本。

# 添加一个明确版本的依赖，Go 会同步调整 go.mod 与需要的校验记录
go get example.com/acme/logkit@v1.4.2

# 按当前源码、测试和构建约束整理依赖声明与 go.sum
go mod tidy

# 查看本次依赖操作留下的文件变化，重点关注 go.mod 和 go.sum
git diff -- go.mod go.sum

go mod tidy 不是“删除所有看起来没用的校验和”的命令。它根据模块加载结果更新文件，所以应在正确的构建标签、测试依赖和 Go 版本环境下执行。若项目有不同平台的文件或生成代码，先确认这些输入是否已经准备好，再判断 diff 是否合理。

看懂校验来源：代理、校验数据库与私有模块

公开模块通常会通过 GOPROXY 查找，成功下载后由 Go 的模块校验机制核对内容。企业项目还可能设置 GOPRIVATE，告诉 Go 哪些模块路径属于私有范围，避免把私有模块交给公共代理或公共校验服务处理。

# 公开依赖优先使用组织允许的代理，失败后再按策略直连
go env -w GOPROXY=https://proxy.golang.org,direct

# 私有模块按组织域名配置，避免走公共代理和公共校验服务
go env -w GOPRIVATE=git.example.com/team/*

# 查看当前配置；输出只用于排查本机环境，不要把凭据写进仓库
go env GOPROXY GOPRIVATE GONOSUMDB GONOPROXY GOSUMDB

私有模块是否产生校验记录，要结合组织的代理与校验服务策略判断。不要因为看到某条私有路径就直接删掉对应的 go.sum 行，也不要把访问令牌写进 go.mod、go.sum 或脚本。环境变量负责访问边界，版本库里的文件负责依赖声明和可追溯变更。

代码评审时怎样判断 go.sum diff

一组正常的依赖变更通常同时解释三个问题：是谁引入了模块版本、为什么出现新增或删除的校验行、源码是否真的需要这个版本。评审可以按下面的顺序缩小范围：

1. 先看 go.mod 的直接依赖、间接依赖和版本变化。
2. 再看 go.sum 中新增行是否对应这些版本，是否包含模块内容和模块元数据的记录。
3. 如果只改了 go.sum，追问是哪条命令或哪个构建标签触发；不要直接手删。
4. 如果大量无关行变化，确认是否切换了 Go 版本、代理、构建标签或工作区状态。

可以把依赖变更拆成独立提交，让评审更容易把源码修改与依赖修改对应起来。提交信息写清“新增哪个模块、用于哪个功能”，比在 go.sum 里添加人为注释更有价值，因为 go.sum 是工具维护的格式。

让 CI 用只读模式阻止隐式修改

本地开发需要让 Go 命令更新文件，但 CI 更适合验证仓库状态是否完整。可以使用 -mod=readonly 执行测试或构建；如果当前模块解析需要改写 go.mod 或 go.sum，命令会直接暴露这个问题，而不是在流水线工作区里悄悄生成一个未提交文件。

# CI 只读检查依赖文件，缺少记录时让任务直接失败
go test -mod=readonly ./...

# 构建也使用同一约束，避免构建过程替仓库补写依赖文件
go build -mod=readonly ./cmd/server

只读模式不是网络隔离开关，它仍可能按组织配置下载模块；它的重点是“不允许本次命令为了完成解析而修改模块文件”。如果 CI 失败，先在与 CI 相同的 Go 版本、构建标签和代理设置下运行 go mod tidy，审阅结果后再提交，而不是把 CI 产物直接覆盖回仓库。

哪些做法容易把提交策略弄乱

• 手工删除 go.sum：文件变小不等于依赖更安全，下一次解析可能又把记录写回来。
• 只提交 go.mod：新环境可能缺少可比对的校验记录，问题会延迟到构建阶段才暴露。
• 把 GOPRIVATE 当作清理开关：它描述私有模块边界，不代表可以删除已有依赖记录。
• 在 CI 中无条件运行 tidy：流水线会把环境差异带进工作区，应该把整理动作放在可评审的开发步骤。
• 忽略工具链差异：Go 版本、构建标签和代理配置变化，都可能影响模块加载结果。

一份可执行的提交清单

相关问题

go.sum 可以加入 .gitignore 吗？

一般不建议。对需要提交的 Go Modules 项目，go.sum 是依赖校验记录，应纳入版本控制；只有明确采用了不同的依赖供应链方案时，才按组织规范处理。

go.sum 有冲突时应该怎么合并？

先保留源码和 go.mod 的真实变更，解决 go.mod 后在统一环境中重新运行 Go 命令生成 go.sum，再审阅完整 diff。不要只按文本行拼接两个版本的校验记录。

为什么 go mod tidy 后 go.sum 仍然变大？

它可能加载了测试依赖、平台相关文件或新的间接模块。先确认构建标签、测试范围和 Go 版本，再决定这些记录是否与项目实际使用一致。

归纳起来，go.sum 的提交原则很简单：让 Go 工具生成，让评审解释，让 CI 只读复查。只要依赖来源、私有边界和工具链环境都能说明白，校验记录多几行并不是问题，无法解释的变化才值得停下来排查。