go.sum 是 Go 模块完整性校验文件，记录各依赖模块 zip 包及 go.mod 的 SHA256 哈希值，确保每次下载内容与首次构建一致，防止篡改；它由工具链自动生成，用于“验内容”而非锁版本，必须提交至版本库以保障构建可重现。

Go 通过 go.sum 文件自动记录每个依赖模块的加密哈希值，确保每次下载的第三方库内容与首次构建时完全一致，防止依赖被篡改或替换。这是 Go 模块（Go Modules）完整性保护的核心机制。

go.sum 是什么，为什么需要它

go.sum 是一个由 Go 工具链自动生成和维护的文件，每行包含一个模块路径、版本号和两个哈希值（h1: 开头的是模块 zip 包的 SHA256 哈希，go.mod 后面的是该模块 go.mod 文件的哈希）。它的作用不是“锁版本”（那是 go.mod 的职责），而是“验内容”——哪怕模块作者在相同版本下偷偷修改了代码，go.sum 就会校验失败，阻止构建继续。

启用 Go Modules 后（即项目根目录有 go.mod），只要执行过 go build、go test 或 go list 等命令，Go 就会自动更新 go.sum。它默认开启，无需额外配置。

如何触发和更新 go.sum

大多数情况下你不需要手动操作，但需了解关键行为：

• 首次运行 go mod tidy 或 go build 时，Go 会下载依赖并生成 go.sum 条目
• 添加新依赖（如 go get github.com/sirupsen/logrus@v1.9.0）后，go.sum 会自动追加对应条目
• 升级依赖版本后，旧版本的哈希可能保留在 go.sum 中（用于历史校验），新版本条目会被加入
• 执行 go mod tidy -v 可看到哪些模块被校验、是否命中缓存、是否重新计算哈希

校验失败时怎么办

当 go build 或 go mod download 报错类似 checksum mismatch，说明本地下载的内容与 go.sum 记录的哈希不一致。常见原因和应对方式：

• 模块源被污染（如代理仓库缓存损坏）：运行 go clean -modcache 清空模块缓存，再重试
• 本地修改了某个依赖的源码（比如 replace 指向本地路径但内容变了）：检查 go.mod 中的 replace 语句，确认本地代码是否应被提交或更新哈希
• 想接受新内容并更新记录：用 go mod download -dirty 跳过校验（仅调试用），或更安全地执行 go mod verify 查看差异，再决定是否 go mod tidy 以更新 go.sum

协作与 CI 中的最佳实践

go.sum 必须提交到版本库，否则不同开发者或 CI 环境会因依赖内容不一致而出现不可复现的问题。

• CI 流水线中建议在 go build 前加一步 go mod verify，显式校验所有依赖完整性
• 避免手动编辑 go.sum；如有冲突，优先以主干分支的 go.sum 为准，再运行 go mod tidy 同步
• 使用私有模块代理（如 Athens、JFrog GoCenter）时，确保其支持校验和转发，否则可能绕过 go.sum 保护