go.sum 锁定的是每个模块实际下载的 zip 包及 go.mod 文件内容的 sha256 哈希值，确保同名版本字节级一致；校验失败时需验证来源并运行 go mod download 更新。
go.sum 文件到底锁了什么
它不锁版本号，也不锁 go.mod 里写的 require 版本；它锁的是每个模块**实际下载到本地的 zip 包内容的哈希值**。也就是说，哪怕你写的是 v1.2.3，只要上游悄悄重发了同名 tag（比如修复了 zip 打包逻辑但没改 commit），go.sum 就会校验失败——Go 拒绝构建。
常见错误现象：verifying github.com/some/pkg@v1.2.3: checksum mismatch
- 原因通常是：模块发布者用
git tag -f强制覆盖旧 tag，或在相同 tag 下重新打包发布 - Go 不信任远程仓库的“语义”，只认本地缓存解压后的真实字节
-
go.sum每行格式是：module/path v1.2.3 h1:xxx...或module/path v1.2.3/go.mod h1:yyy...，后者校验的是该模块自身go.mod文件的哈希
什么时候 go.sum 会被自动更新
不是每次 go get 都改 go.sum，只有真正触发模块内容下载（且未命中本地缓存）时才追加或更新条目。典型场景：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 首次
go mod download或go build，所有依赖第一次拉取 -
go get some/pkg@v1.4.0升级后，新版本的哈希被写入 - 删掉
$GOPATH/pkg/mod/cache后重新构建，即使版本没变，也会重算并可能更新哈希（比如 Go 工具链升级导致解压/归档方式微调） -
go mod tidy会清理未被引用的go.sum条目，但仅限于整个模块路径+版本组合完全未出现在go.mod的require中
go.sum 校验失败时怎么安全处理
别急着删 go.sum 或加 -mod=mod 跳过。先确认是不是真的该信新哈希：
- 用
go list -m -json some/pkg@v1.2.3看 Go 当前解析出的实际 commit 和 source URL - 手动访问该 URL 对应的 zip 链接（如
https://github.com/some/pkg/archive/v1.2.3.zip），用shasum -a 256 xxx.zip算哈希，对比go.sum里h1:开头的值（注意：Go 用的是 base64 编码的 sha256，不是原始 hex） - 如果哈希确实变了，且你信任发布源，运行
go mod download some/pkg@v1.2.3让 Go 重写go.sum条目；不要手动编辑go.sum - 如果不确定变更来源，用
go mod graph | grep some/pkg查谁引入了它，再决定是锁定更老的兼容版本，还是联系上游确认发布流程
CI/CD 中 go.sum 的关键注意事项
很多团队把 go.sum 提交进 Git，但忽略两个硬性前提：
- 所有开发者和 CI 必须使用**相同 major 版本的 Go 工具链**（如都用 Go 1.21.x）。不同 Go 版本对同一 zip 包计算的哈希可能不同（尤其涉及
/go.mod行尾、注释处理等细节） -
GO111MODULE=on必须显式设置，否则在 GOPATH 模式下go.sum不生效，CI 可能跳过校验 - CI 构建前不要执行
go clean -modcache，否则会强制重拉并可能写入新哈希，导致本地开发与 CI 行为不一致 - 私有模块代理（如 Athens、JFrog）必须透传原始哈希，不能用自己的缓存重算——否则
go.sum失效
最常被忽略的一点：go.sum 不防中间人篡改模块代码，只防“同名版本内容不一致”。它依赖 Go 工具链从源站下载时的 TLS 和证书验证，一旦代理或 DNS 被劫持，哈希再准也没用。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
