Go 模块为什么出现 checksum mismatch

Go模块出现 checksum mismatch，表示同一模块路径和版本对应的下载内容，与工具链用于认证它的已知校验记录不一致。原因可能是项目go.sum被错误改动、缓存或代理内容异常，也可能是发布者改写了已发布版本。应先保留错误与版本信息，再定位差异来源，不要直接删除go.sum或关闭校验来让构建继续。

官方地址：https://go.dev/

面对“同事能构建，我却下载失败”的场景，我会先把它当作依赖身份发生分歧处理，而不是先清空所有记录。这里采用的是排障顺序与判断方法，不把任何假设写成真实发生过的个人安全事故。

先保留不一致的模块身份

记录报错中的模块路径、精确版本、下载对象及两侧校验值。尤其要区分模块压缩包与版本后带/go.mod的记录：后者认证的是go.mod内容，两者不是重复的同一个摘要。

# 在发生错误的模块目录记录工具链与依赖来源配置。
go version
go env GOMOD GOWORK GOPROXY GOSUMDB GOPRIVATE GONOSUMDB GOMODCACHE
# 查看项目记录是否在最近提交或冲突解决中改变。
git diff -- go.mod go.sum

这些命令供读者在自己的项目执行，本文未运行依赖检查。环境输出可能含企业代理地址或私有模块信息，对外分享前应去掉凭据和内部路径。不要只发最后一行错误而遗漏它究竟在比对哪个版本。

若分支中的go.sum有手工替换、冲突残留或来自不明来源的摘要，先与经过审核的提交比较。历史记录也需要可信来源支持，不能因为某一份记录更容易通过就认定它正确。

理解下载内容与信任记录的关系

下载得到的模块内容需要与已有记录对应。go.sum保存项目接受过的摘要；公开模块缺少相应记录时，默认机制还会向校验数据库查询。数据库不可达通常是连接或查询错误，不能把它与已经得到两个不同摘要的mismatch混为一谈。

Go模块压缩包的认证关注归档中文件名与内容的确定性组合，不等同于直接对下载zip文件做普通文件SHA256。仅改变压缩顺序、压缩参数或zip元数据，不应被解释为模块内容摘要变化的充分原因。

“不一致”是停止接受内容的依据，但还不能单凭它断言遭到攻击。可以先列出本地记录错误、缓存被改、代理分发异常与版本内容改写几条路径，再用可追溯证据缩小范围。

用独立缓存区分本地修改

先在项目副本或临时工作目录中保留原go.mod、go.sum，再使用一个新的模块缓存下载相同精确版本。下面是POSIX Shell示例，其中模块名与版本都是占位值，需要改成报错里的真实值。

# 创建独立诊断缓存，保留原缓存供比较；只对本次命令生效。
diag_cache=$(mktemp -d)
# 用真实模块路径和精确版本替换占位值，沿用既有认证配置。
GOMODCACHE="$diag_cache" go mod download -json example.com/team/library@v1.2.3

若独立缓存仍出现同样不一致，说明不能只归因于原缓存目录中的文件被手工修改。若新缓存正常而旧缓存异常，可进一步追踪旧缓存是否被编辑、错误恢复或共享工具污染，但一次成功也不等于解释已经完成。

诊断目录的路径保存在diag_cache变量中；问题定位后按团队临时目录规则清理，避免长期占用空间。这里不建议第一步运行全局go clean -modcache，它会清除其他项目共享的模块缓存，并且丢失现场。

go mod verify可帮助发现缓存中的模块zip或解压目录自下载后被改动，但它不是下载认证的替代命令，也不是通过go.sum重新认证所有模块内容的工具。它主要比较缓存对象与下载时记录的摘要；必要的模块图处理仍可能读取或下载go.mod。因此不要把“缓存未变”直接等同于“来源一定可信”。

按内容来源处理不同原因

Go版本代表不可变内容快照。维护者不能通过移动同名标签来更新已有版本，再要求所有消费者替换校验值。旧内容可能已经被代理缓存，改标签会让不同用户拿到不同对象；应使用新版本表达新内容。

若是私有模块，核对GOPRIVATE、GONOSUMDB与企业代理策略是否精确覆盖实际私有前缀，并在企业可信发布体系内核实内容。私有依赖不使用公开数据库并不意味着同一个已记录版本可以任意变更。不要把通配范围扩大到所有模块来掩盖问题。

恢复构建前留下可追溯记录

修复后记录采用的模块路径、版本、来源配置、可信依据与go.mod/go.sum变动。重试同一个精确版本时，应保留正常认证机制；需要升级则通过代码审核提交新版本和相应依赖记录，而不是静默替换摘要。

删除go.sum再tidy为什么看起来能解决？

删除会移走项目原有认证记录。公开模块仍可能被数据库拒绝；未使用公开认证的模块则可能接受当前下载内容。构建通过并不能证明原差异已经解释，所以不把它作为常规修复。

关闭GOSUMDB就没有校验了吗？

它会关闭公开校验数据库查询，但已有go.sum记录仍有意义，也不能把不一致变成可信。不要把关闭认证作为消除错误的目标。

checksum mismatch和缺少go.sum条目一样吗？

不同。缺失条目是没有对应记录，不一致是内容与已有认证依据冲突。处理前应先看清完整错误。

排障终点应是解释并修复内容来源或记录的差异。保留同一模块身份，分别看项目记录、缓存与分发来源，才能避免把完整性异常降格成一次“删文件重试”。

官方资料：模块认证机制；go mod verify说明。