go.sum 校验失败时如何区分镜像与版本问题

遇到 verifying module: checksum mismatch 时，先不要急着删除 go.sum 或关闭校验。这个现象至少有两条完全不同的路径：一条是同一个模块版本从镜像或缓存拿到了与既有校验不一致的内容，另一条是项目实际要用的版本已经变化，go.mod、go.sum 和下载目标没有同步。

判断的关键不是“能不能重新下载”，而是把模块路径、版本、go.mod 校验项、zip 校验项和下载来源逐一对上。本文只处理这组判断。

官方资料：https://go.dev/ref/mod

先看报错属于哪一类

把终端信息先按下面三类归档，后续动作会更准确：

这里的 /go.mod 不是普通版本的另一种写法。它表示校验的是模块的 go.mod 文件；不带后缀的条目通常对应模块 zip 内容。两者不能互相替代。

先把 go.mod 和 go.sum 对齐

在项目根目录先确认 Go 命令看到的模块边界，再查目标模块在两个文件里的记录。下面的命令只读取信息，不修改依赖文件：

# 查看当前命令使用的模块边界和代理设置
go env GOMOD GOPROXY GOSUMDB GOPRIVATE

# 将目标模块替换成报错中的真实模块路径与版本
go mod download -json example.com/library@v1.2.3

go mod download -json 的结果重点看 Path、Version、Sum、GoModSum 和 Error。不要只看文件名；同一个模块路径的不同版本是不同的校验对象。

# 同时查看模块声明、替换规则和目标版本的校验条目
grep -nE '^(module|require|replace)' go.mod
grep -nE '^example\.com/library ' go.sum
grep -nE '^example\.com/library .* /go\.mod$' go.sum

如果 go.mod 已经从 v1.2.2 改成 v1.2.3，但排障时仍拿旧版本的校验项作判断，优先按版本问题处理。反过来，如果 go.mod 和 go.sum 都指向同一个路径、同一个版本，却在获取内容时出现不匹配，再继续查来源。

用下载结果区分版本问题和镜像问题

接下来把“目标是什么”和“从哪里拿到”分开记录。可以先查看当前环境：

# 记录当前代理链和校验数据库，避免把环境差异误判成版本差异
go env GOPROXY GOSUMDB GOPRIVATE GONOSUMDB

# 只针对报错模块获取 JSON 元数据，便于比较路径、版本和错误字段
go mod download -json example.com/library@v1.2.3

如果两次命令的 Path、Version 不同，那是目标版本没有固定，应该回到 go.mod 或上游依赖图；如果路径和版本完全相同，但代理链改变后 Sum、GoModSum 或错误表现发生变化，才有理由优先怀疑代理或缓存路径。

切换下载来源时要保持校验开启

为了确认是不是某个镜像返回了异常内容，可以在同一个模块版本上换一个可信来源做对照。不要把关闭校验当成修复方案：

# 用显式代理做一次对照；保留校验数据库，避免把错误内容当成正确依赖
GOPROXY=https://proxy.golang.org go mod download -json example.com/library@v1.2.3

# 再用 direct 对照源代码仓库；仍然让 Go 按 go.sum 和校验数据库检查内容
GOPROXY=direct go mod download -json example.com/library@v1.2.3

两次结果只应比较同一模块、同一版本。若代理失败而 direct 成功，或不同来源返回的内容校验表现不一致，先检查代理缓存是否陈旧、是否错误地镜像了同一版本；若两者都提示本地记录与目标版本不一致，则更像是版本声明或 go.sum 条目已经过时。

代理链还受 HTTP 状态影响，不能把“换了第二个代理”简单理解为每次失败都会自动切换。排障时应把实际的 GOPROXY 值和错误内容一起记录。

对应修复动作：镜像、缓存和版本分别处理

镜像或缓存路径异常

先确认团队是否使用了自建代理、共享模块缓存或内部镜像。对同一版本做来源对照后，优先修复镜像同步或缓存内容，不要直接改写既有校验值。必要时在干净的模块缓存中重试，让结果与公共校验记录重新比对。

# 清理当前用户的模块下载缓存，下一次命令会重新获取目标内容
go clean -modcache

# 重新下载目标版本并输出元数据，确认错误是否仍然指向同一版本
go mod download -json example.com/library@v1.2.3

清缓存只能排除本地缓存损坏，不能修复代理端返回了错误内容的问题。如果清缓存后仍然只有某个镜像失败，应把镜像地址、模块路径和版本交给维护镜像的人处理。

版本或依赖图发生变化

如果项目确实完成了升级、降级或替换，就让 Go 根据当前代码和模块声明重新整理依赖：

# 根据当前源码、构建标签和模块声明整理依赖，并同步 go.sum
go mod tidy

# 查看最终选择的模块版本，确认没有被间接依赖重新抬高或降低
go list -m all

这类场景的重点是审阅版本变更本身，而不是把旧的 go.sum 行手工复制回来。若 CI 与本地结果不同，还要确认两边的 Go 版本、构建标签、工作目录和私有模块配置一致。

私有模块不能套用公共镜像判断

如果报错模块属于公司内部路径，先检查 GOPRIVATE、GONOPROXY 和 GONOSUMDB 的边界。公共校验数据库无法替私有模块计算公开记录；这时应使用组织自己的代理或校验策略，并避免把私有路径发送到不该接收它的公共服务。

一张可复用的判断清单

1. 记录完整报错，确认是 checksum mismatch、缺条目，还是下载失败。
2. 确认 go.mod 中的模块路径和版本，再对照 go.sum 的普通条目与 /go.mod 条目。
3. 用 go mod download -json 固定同一模块、同一版本，记录 Sum、GoModSum 和错误字段。
4. 保持 GOSUMDB 等校验机制开启，只改变 GOPROXY 做来源对照。
5. 同一版本在不同来源表现不同，先查镜像和缓存；版本或依赖图不同，先查 go.mod。
6. 版本升级完成后运行 go mod tidy，不要手工伪造或覆盖校验值。

相关问题

删除 go.sum 能解决校验失败吗？

不能把它当成通用修复。删除后 Go 可能重新生成条目，但如果根因是镜像返回了不同内容，问题会再次出现；如果根因是版本声明混乱，删除也会掩盖依赖变更。

为什么 go.sum 里只有 /go.mod 条目？

这通常表示当前流程只需要校验模块的 go.mod 文件，或模块 zip 还没有被实际下载使用。要结合 go.mod 的版本和当前导入包判断，不能单凭这一行认定镜像损坏。

可以把 GOSUMDB=off 当作排障步骤吗？

不建议。关闭校验会改变问题性质，无法帮助判断镜像返回的内容是否可信。更稳妥的做法是固定版本、对照下载来源，并保留校验机制。