Go checksum mismatch 的 go.sum 修复边界

Go 项目遇到 checksum mismatch 时，最重要的动作不是先删掉 go.sum，而是确认到底是哪一份内容与哪一个可信来源不一致。Go 会对下载到模块缓存中的模块压缩包和 go.mod 计算校验和；已有记录不一致时会报安全错误，公共模块缺少记录时还可能通过 checksum database 补充验证。

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

安全的修复边界是：先保留报错现场，区分缓存损坏、依赖版本被重新打标签、公共校验数据库冲突和私有模块配置错误；只有确认来源与版本都正确后，才让 Go 重新生成必要的 go.sum 条目。不要用删除校验文件或全局关闭 GOSUMDB 来掩盖不一致。

• 可以修复缓存：本地缓存中的文件与既有校验不一致，且远端同一版本仍能提供一致内容。
• 需要换版本：同一个公开版本被重新打包或重新打标签，不能把新内容直接写回旧校验。
• 需要改配置：模块是私有路径，却被错误地送去公共代理或 checksum database。
• 不能绕过：来源无法确认、校验数据库与下载内容冲突，或团队无法解释版本变化。

先看懂 checksum mismatch 指向的对象

同样一句 checksum mismatch，可能出现在模块压缩包，也可能出现在模块的 go.mod 文件。报错行里的模块路径、版本和 verifying module 或 verifying go.mod 文字，决定后续排查对象。go.sum 不是普通的下载缓存索引，而是项目对依赖内容的已知校验记录；它和本地缓存、代理、校验数据库共同构成信任链。

第一步：把现场信息保存下来

先记录发生错误的模块和版本，再保存影响下载与验证路径的环境变量。下面的命令只读取环境，不修改项目文件，适合放进排障记录中。

# 记录模块下载与校验链路，避免修复后丢失原始环境
go env GOPROXY GOSUMDB GOPRIVATE GONOSUMDB

# 查看当前主模块声明的依赖，确认报错版本是否来自预期的构建图
go list -m all

# 针对报错模块输出下载位置、go.mod 校验和与压缩包校验和
go mod download -json example.com/blocked/module@v1.2.3

go mod download -json 的结果可以帮助区分 GoModSum 与 Sum。不要只复制报错中的新哈希覆盖 go.sum；先确认模块版本和来源确实应该变化。

缓存不一致时，只修复缓存，不改信任记录

如果同一模块版本在团队和持续集成环境中都应保持不变，而只有某台机器报错，优先怀疑本地模块缓存被中断下载、磁盘问题或人工改动。此时可以在隔离环境清理模块缓存，再让 Go 按现有依赖重新下载。go clean -modcache 会清理整个模块缓存，可能影响同机上的其它项目，所以不应把它当作每次报错的默认命令。

# 该操作会清理当前用户的整个模块缓存，先确认不会影响并行构建
go clean -modcache

# 让 Go 重新取回依赖并按既有校验链路验证
go mod download

# 检查模块缓存中的已下载内容是否被改动
go mod verify

如果清理后仍然得到相同的校验冲突，问题就不再像单机缓存污染。保留错误信息，转到版本来源或代理配置排查，不要继续重复清缓存。

版本内容被重新打标签时，不能覆盖旧 go.sum

一个已经被团队使用的公开版本，若后来被重新打包或把同一个标签指向了不同内容，旧的 go.sum 就是在提醒你“同一路径和版本的内容发生了变化”。Go 官方文档把这类情况视为安全错误。正确处理方式是联系维护者或确认发布记录，选择一个内容稳定、版本标识不同的版本，然后通过依赖管理命令更新。

# 先把目标模块固定到维护者确认的新版本，不直接改旧哈希
go get example.com/blocked/module@v1.2.4

# 根据当前源码引用同步 go.mod 与 go.sum
go mod tidy

# 复查最终依赖缓存中的内容完整性
go mod verify

如果维护者明确说明旧版本确实被误发布，团队应把版本变更和原因写入提交记录。仅删除一行旧哈希，或者把下载得到的新哈希手工粘回原版本，会让后续构建失去可解释性。

公共校验数据库冲突时，先停下发布

对于公开模块，Go 在 go.sum 缺少某个下载内容的记录时，默认会通过 checksum database 获取已知校验。如果下载内容与数据库提供的校验不一致，应该把它当作供应链风险或代理内容异常处理，而不是当作普通格式问题。此时不应通过 GOSUMDB=off 继续发布。

# 只读取当前校验数据库设置，确认是否被脚本意外关闭
go env GOSUMDB

# 对目标模块重新请求下载信息，保留完整错误输出供维护者比对
go mod download -json example.com/blocked/module@v1.2.3

# 在确认版本来源后，再让依赖图同步，而不是先改写 go.sum
go mod tidy

GOSUMDB=off 只改变校验数据库的使用方式，并不能证明下载内容是可信的。若公司代理有自己的校验数据库或镜像，应按组织的安全策略配置对应的 GOPROXY 与 GOSUMDB，并保留变更依据。

私有模块要收窄信任范围

私有模块通常不应该被发送到公共代理或公共 checksum database。可以用 GOPRIVATE 指定私有路径模式；它会作为 GONOPROXY 和 GONOSUMDB 的默认值。下面的示例只把公司域名交给私有下载路径，公共模块仍保持默认校验。

# 只对公司私有模块设置边界，公共依赖仍走正常校验
go env -w GOPRIVATE=corp.example.com/*

# 如果组织使用私有代理，按公司文档替换为可访问的代理地址
go env -w GOPROXY=https://proxy.corp.example.com,direct

# 查看最终配置，确认没有把所有模块都放进私有范围
go env GOPROXY GOPRIVATE GONOPROXY GOSUMDB GONOSUMDB

实际域名、代理地址和凭据应由组织提供，文章中的 corp.example.com 只是占位示例。不要把访问令牌写进 go.mod、go.sum 或提交记录。

提交前用一张清单收口

修复完成后，重点是确认改动可解释，而不是追求工作区没有任何差异。

# 确认依赖图与源码引用一致，允许 go.sum 产生必要条目
go mod tidy

# 检查模块缓存中的已下载内容没有被改动
go mod verify

# 查看待提交的依赖变化，人工确认模块路径和版本
git diff -- go.mod go.sum

常见问题

删除 go.sum 再执行 go mod tidy 可以吗？

不应作为默认修复。这样做会丢掉项目原有的依赖校验记录，可能把真正的版本或供应链问题隐藏起来。只有在明确的依赖迁移方案中，才应由团队审查生成的完整差异。

为什么别的项目能下载，同一台机器这个项目却失败？

每个主模块都有自己的 go.sum，项目依赖图、版本和私有模块匹配规则也可能不同。同机成功只能说明某个项目的依赖链路可用，不能替代当前项目的校验。

私有模块能不能全局关闭 GOSUMDB？

不建议。更窄的边界是用 GOPRIVATE 或 GONOSUMDB 匹配私有路径，让公共模块继续接受正常验证；是否使用组织内部校验服务，则按公司策略配置。

什么时候应该停止修复并升级给维护者？

当同一公开版本持续与 checksum database 冲突、代理返回内容无法解释、或发布者不能确认版本来源时，应保留完整错误和环境信息，暂停该依赖的发布，等待维护者或安全负责人给出版本决策。