go.sum 是 Go 模块校验和数据库，每行记录模块版本的 SHA-256（h1）及对应 go.mod 的 h1 校验和，确保依赖内容一致、防篡改；它只增不减，必须与 go.mod 一同提交至 Git。
Go 项目中依赖版本锁定靠 go.mod 和 go.sum 共同完成，但二者分工明确：go.mod 记录你「声明」要什么版本，go.sum 记录你「实际下载」的每个模块校验和——它才是防篡改、保一致的关键。
go.sum 文件到底存了什么
go.sum 是模块校验和数据库，每行对应一个模块版本的两种哈希值：h1（SHA-256）和 go.mod 文件自身的 h1 校验和。它不记录依赖树结构，只保证：只要模块路径+版本相同，内容就必须和历史一致。
常见错误现象：
- 拉取私有模块时提示
verifying github.com/xxx@v1.2.3: checksum mismatch -
go build失败并报missing go.sum entry - 团队成员
go run行为不一致，有人报错有人正常
这些基本都指向 go.sum 缺失、过期或被手动修改过。
什么时候会更新 go.sum
不是每次 go get 都自动追加或刷新 go.sum，只有满足以下任一条件时才会写入或修正：
- 首次运行
go mod tidy或go build且项目无go.sum - 引入新模块（如
go get github.com/sirupsen/logrus@v1.9.0），且该模块未在go.sum中出现过 - 模块版本内容变更（比如作者重推 tag、私有仓库提交 force push），导致校验和不匹配，此时
go命令会拒绝继续并提示错误，需人工确认是否接受新哈希（用go mod download -dirty或删go.sum后重试，但不推荐）
注意：go.sum 不会因 go.mod 中版本号降级而自动清理旧条目；也不会因模块被移除而自动删除对应行——它只增不减，除非手动删。
go.sum 被忽略或误删后怎么办
Git 忽略 go.sum 是严重错误配置。它必须和 go.mod 一起提交，否则无法复现构建环境。
如果已误删或遗漏：
- 执行
go mod download可重新生成全部校验和（前提是go.mod正确且网络可达） - 若部分模块不可达（如私有 registry 认证失败），会卡住并报错，此时需先配置好
GOPRIVATE和NETRC等认证信息 - 不要用
go mod init重建go.sum—— 它只处理go.mod，不会补go.sum
go mod download # 成功后会输出类似： # github.com/golang/freetype v0.0.0-20170609003504-e23677dcdc8b h1:u/69SfLQaeqJZzFtKUaIwOjXyYk7gGmE8TqVxMnCwXs= # github.com/golang/freetype v0.0.0-20170609003504-e23677dcdc8b/go.mod h1:8D4A1iPv5r3t4NcYdYz1k6BZ+3eW4KZqk7cXvYyKjZQ=
CI/CD 中 go.sum 的典型陷阱
很多 CI 流水线默认缓存 go/pkg/mod，却忽略 go.sum，结果导致本地能过、CI 报 checksum mismatch。
关键点：
-
go.sum必须参与 Git 版本控制，且每次go mod tidy后都要检查其变更 - CI 中不应跳过
go mod verify（它会校验go.sum是否与当前go.mod匹配） - 如果使用
go install安装工具（如golangci-lint），其依赖也应纳入go.sum—— 推荐用go install example.com/tool@v1.2.3显式指定版本，并确保该命令在项目根目录下执行，以便写入当前项目的go.sum
最常被忽略的是：go.sum 不是“可选附件”，它是 Go Module 模式下唯一能防止依赖投毒和静默升级的机制。少一行，就可能让整个构建链路失去确定性。
