Go module checksum mismatch 如何判断代理缓存问题

遇到 verifying module: checksum mismatch 时，先不要删除整个 go.sum，也不要直接设置 GOSUMDB=off。Go 校验的是某个模块路径和版本对应的 go.mod 或源码 zip 内容：如果下载内容与本地记录或 checksum database 的哈希不同，命令会把它当成安全错误拒绝安装。排查重点是固定同一个 path@version，再比较“下载来源”和“校验依据”。

官方参考地址：https://go.dev/ref/mod

一、先固定模块路径、版本和当前下载配置

“代理缓存有问题”不是第一结论。先从报错中取出模块路径和版本，例如 example.com/lib@v1.2.3，然后记录当前环境。模块路径、版本或校验设置只要有一个变化，对照结果就没有可比性。

# 只读取当前生效设置，先不要用 go env -w 改写全局配置
go env GOPROXY GOSUMDB GOPRIVATE GONOPROXY GONOSUMDB

# 输出指定模块的下载元数据；path@version 要替换成报错中的精确对象
go mod download -json example.com/lib@v1.2.3

重点看返回对象里的 Sum、GoModSum、Zip、GoMod 和 Error。Sum 对应源码 zip，GoModSum 对应模块的 go.mod；只看其中一个，可能漏掉“源码一致但 go.mod 不一致”的情况。

二、用 go.sum、模块 zip 和 checksum database 对照哈希

go.sum 里已经有该版本记录，而新下载的 Sum 不同，说明“当前拿到的内容”与项目曾接受的内容不一致。对公开模块来说，同一个版本不应因为换了普通代理就变成另一份源码，这时应优先怀疑代理对象、缓存污染、错误的版本来源或上游不当重用版本号。

如果本地没有这条 go.sum，Go 通常会向 GOSUMDB 指定的 checksum database 查询已知哈希，再决定是否接受下载内容。若日志同时出现 downloaded hash 和 checksum database hash，且两者不同，这是安全拒绝，不是“少执行一次 tidy”这么简单。

# 在当前项目根目录检查依赖缓存中的内容是否被改动
go mod verify

# 只查看整理会产生哪些 go.mod/go.sum 变化，不直接写文件
go mod tidy -diff

go mod verify 更适合检查本地下载缓存是否在下载后被改动；它不能替代 checksum database，也不能证明代理返回的内容正确。go mod tidy -diff 可以帮助观察缺失或多余记录，但当错误明确是校验不一致时，不要用 tidy 的改动覆盖证据。

三、用 GOPROXY 与 direct 做来源对照

对同一个公开模块，可以临时改变 GOPROXY 做对照。下面的写法只对当前命令生效，不会把设置写入用户环境；同时保留 GOSUMDB，这样比较的是代理来源，而不是把安全门禁拆掉。

# 从公共代理取同一个版本，适合与企业代理结果作基线对照
GOPROXY=https://proxy.golang.org go mod download -json example.com/lib@v1.2.3

# 直接访问模块声明的版本控制来源；仍会按当前 GOSUMDB 规则验证
GOPROXY=direct go mod download -json example.com/lib@v1.2.3

如果企业代理失败而公共代理与 direct 都能得到一致校验值，问题更像是企业代理的缓存或重打包流程；如果三种来源都被同一个 checksum database 拒绝，继续换代理没有意义，应核查模块版本是否真的对应预期提交。反过来，如果模块是私有的，direct 可能只是绕过了企业代理，不能拿公开模块的判断规则硬套。

四、按公开模块和私有模块分别修复

公开模块出现不一致时，保留校验并修复来源：确认代理没有缓存坏 zip，检查是否把不同仓库内容错误映射到同一个版本，并让上游发布新的合法版本。不要为了让构建通过而删掉正确的 go.sum 行或关闭 GOSUMDB；那会把“内容变了”变成“没人再核对”。

私有模块的重点是隐私和信任边界。GOPRIVATE 可以把匹配的模块视为私有，默认避免公共代理和 checksum database；如果公司有可信的内部代理，再按需要设置 GONOPROXY 和 GONOSUMDB。配置应尽量使用明确的路径前缀，例如：

# 私有模块不送往公共代理和公共 checksum database
GOPRIVATE=*.corp.example.com

# 如果内部代理负责提供私有模块，可保留代理、只跳过公共校验库
GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org
GONOSUMDB=*.corp.example.com

最后把 go.mod 和 go.sum 一起纳入评审与构建输入。这样下一台机器遇到同一个版本时，能判断它是复现了项目记录，还是来自另一套代理规则，而不是重新猜测“是不是缓存”。

常见问题

把 GOPROXY 改成 direct 后还报 checksum mismatch，说明什么？

说明改变下载来源没有消除哈希分歧；公共模块应继续检查版本内容与 checksum database，而不是关闭 GOSUMDB。

删掉 go.sum 再执行 go mod tidy 能不能修好？

不建议作为第一步。它会抹掉项目原有的对照记录；应先保存报错、path@version 和下载元数据，再决定是否只补缺失记录。

GONOSUMDB 能不能解决所有 checksum mismatch？

不能。它只适合明确属于私有信任边界的模块；对公开模块使用它会降低验证范围，不能修复代理返回错误内容。