checksum mismatch 错误本质是内容校验失败，即go工具链计算的模块哈希值与go.sum中记录的不一致，表明该模块内容不可信；常见诱因包括代理返回污染包、作者强制覆盖tag、replace指向修改后的本地路径或首次构建时依赖快照不一致。
checksum mismatch 错误本质是内容校验失败，不是网络或缓存问题
报错 verifying github.com/some/pkg@v1.2.3: checksum mismatch 的核心意思是：Go 工具链重新计算了本地下载的模块内容哈希值，和 go.sum 里记录的不一致。这不是“拉不到包”，而是明确拒绝使用当前内容——哪怕它能编译通过，Go 也认为它不可信。
常见诱因包括：
- 你配置的
GOPROXY返回了被污染或缓存不一致的 zip 包（比如多个镜像源对同一 tag 返回不同内容） - 模块作者用
git tag -f强制覆盖了已发布的 tag，导致相同版本号对应不同代码 -
go.mod中存在replace指向本地路径，而该路径下代码已被修改，但go.sum记录的是旧哈希 - CI 构建机或新同事机器上缺失
go.sum，首次构建时拉取了与原始环境不同的依赖快照
别删 go.sum，先确认哪个代理在返回脏数据
直接 rm go.sum && go mod tidy 看似能过，但等于放弃所有依赖完整性保护。正确做法是定位污染源：
- 从错误信息中提取模块路径和版本，例如
gopkg.in/src-d/go-git.v4@v4.13.1 - 手动请求各代理的
.mod文件并比对哈希：curl -s https://goproxy.cn/gopkg.in/src-d/go-git.v4/@v/v4.13.1.mod | shasum -a 256<br>curl -s https://goproxy.io/gopkg.in/src-d/go-git.v4/@v/v4.13.1.mod | shasum -a 256<br>curl -s https://proxy.golang.org/gopkg.in/src-d/go-git.v4/@v/v4.13.1.mod | shasum -a 256
- 如果多个代理返回不同哈希，说明其中至少一个缓存已失效；优先选用
proxy.golang.org或与团队一致的镜像源 - 统一设置
GOPROXY=https://goproxy.cn,direct（注意direct是 fallback，不能省略）
go.sum 被自动更新的合法场景只有三个
你不需要、也不应该手动编辑 go.sum。它只在以下三种操作中由 Go 工具链写入：
-
go mod tidy：新增/删除go.mod中的require行后执行，会补全缺失哈希或清理未引用条目 -
go get some/pkg@v1.4.0：升级或降级某个模块时，新版本哈希被追加，旧版本哈希通常保留（用于历史校验） -
go clean -modcache && go build：清空缓存后首次构建，所有模块哈希被重新计算并写入
注意：go mod vendor 不会改动 go.sum；go build 本身也不会改它，除非触发了首次下载或缓存失效。
协作中 go.sum 必须和 go.mod 一起提交
忽略 go.sum 就等于把依赖安全交给运气。它体积小、无敏感信息、纯校验用途，且：
- CI 流水线拉代码后第一次
go build会因缺少go.sum而拉取任意可用版本，可能引入带后门的间接依赖 - 新同事 clone 后直接
go run .，如果没go.sum，工具链会生成新哈希，但这个哈希未必和你本地一致 - 即使项目用了
go mod vendor，仍需保留go.sum——vendor 只解决分发，不替代内容校验
真正容易被忽略的点是：当你用 replace 指向本地路径时，go.sum 记录的是你本地文件的哈希。换机器或删掉本地替换目录，go build 会立刻失败。这种情况下，要么把本地修改提成 PR 合并上游，要么用 go mod edit -replace + go mod tidy 生成对应远程版本的哈希。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
