Go go.sum 校验失败时怎么判断是代理缓存还是源码变化

Go 报出 verifying ... go.mod: checksum mismatch 或模块 zip 校验失败时，先不要删除 go.sum，也不要把 GOSUMDB 全局改成 off。最可靠的判断方法是：先看失败的是 /go.mod 还是模块压缩包，再记录 GOPROXY 和 GOSUMDB，最后用干净的临时模块缓存分别走代理和源码直连。

代理路径失败、模块缓存损坏、同版本源码被重新打包，都会表现为“校验不一致”，但证据不同。只有当 proxy 与 direct 对同一版本给出不同结果，才有理由怀疑代理链路；两条路径都和旧哈希不一致，则应优先检查版本或源码是否真的变了。

一、先分清 go.sum 校验的是哪份内容

go.sum 每行通常有模块路径、版本和 h1: 哈希三个字段。同一版本可能有两行：一行是模块 zip 的哈希，另一行的版本字段以 /go.mod 结尾，表示只校验 go.mod 文件。报错文本中的对象决定了后面的排查方向。

这一步的资产边界是“固定模块版本对应的固定内容”。如果只是缺少哈希，Go 可能向校验数据库查询并补充 go.sum；如果已有哈希却不一致，通常是内容变化或拿到了错误内容，不是简单的“重新生成 go.sum”问题。

二、记录代理和校验数据库的实际路径

不要只看团队文档里的配置，先在报错的模块根目录保存现场：

# 记录下载、校验、私有模块和本地缓存边界
go env GOPROXY GOSUMDB GOPRIVATE GONOSUMDB GOMODCACHE
# 输出目标版本的模块元数据与校验字段
go mod download -json example.com/acme/kit@v1.4.2

这里的 GOPROXY 是下载路径，代理回源可能继续访问版本仓库；模块缓存则是当前机器已经保存的内容。默认配置常见为 https://proxy.golang.org,direct：逗号只在前一个代理返回 404 或 410 时回退，竖线则会对更多 HTTP 错误继续尝试。GOSUMDB 负责公共模块的完整性证明，GOPRIVATE 会影响是否走公共代理和公共校验。

三、用隔离下载比较代理与源码

为同一个模块和版本准备两个临时缓存，分别测试代理和 direct。这样不会被当前用户目录中的旧缓存干扰：

# 固定同一个模块版本，避免比较对象发生变化
module="example.com/acme/kit"; version="v1.4.2"
# 为两条路径创建互不共享的临时模块缓存
tmp="$(mktemp -d)"
# 先验证代理返回的 go.mod 与 zip
GOMODCACHE="$tmp/proxy" GOPROXY="https://proxy.golang.org" go mod download -json "$module@$version"
# 再绕过代理，从源码版本获取同一个模块
GOMODCACHE="$tmp/direct" GOPROXY="direct" go mod download -json "$module@$version"
# 实验结束只清理明确创建的临时目录
rm -rf "$tmp"

如果代理缓存失败而 GOPROXY=direct 成功，重点查企业代理的回源、缓存刷新和错误码；如果两条路径都失败且哈希都不同，重点查版本标签是否被重写、源码是否发生变化，以及 go.sum 是否来自另一个可信构建环境。若两条路径都成功，原问题更可能是当前项目的模块缓存或环境变量差异。

四、按证据选择修复动作

修复动作必须跟证据对应：代理异常就修代理或临时调整回退顺序；源码版本确实变化，就发布一个新的不可变版本并更新依赖；私有模块就补齐 GOPRIVATE、必要时配置 GONOSUMDB。不要因为报错而直接删掉整份 go.sum，也不要用关闭校验数据库来“让构建通过”。

可以把现场证据按下面的关系保存：go.sum 行 是否带 /go.mod 后缀，失败对象是 模块 zip 还是元数据，GOPROXY=direct 是否改变结果，最后再用 go mod verify 检查本地缓存。GOPROXY=direct 只是路径对照，不等于源码一定可信；go mod verify 也只检查本机已经下载的文件。

五、用 verify 和复现记录完成复查

# 只检查当前模块缓存中的依赖是否被改动
go mod verify
# 查看最终依赖图，确认实际选中的模块版本
go list -m all
# 把环境记录到构建日志，便于 CI 与同事复现
go env GOPROXY GOSUMDB GOPRIVATE GONOSUMDB GOMODCACHE

复查记录至少包含模块路径、版本、失败对象、两条下载路径的结果、环境变量和时间。CI 中应固定代理与私有模块规则；当依赖版本需要变化时提交新的版本和对应的 go.sum，而不是提交一次性关闭校验的配置。

相关问题

只缺少 go.sum 行，能不能直接运行 go mod tidy？

可以先确认模块来源和私有边界，再运行 go mod tidy。它适合补齐实际依赖，不适合掩盖已有哈希不一致。

go mod verify 通过，为什么构建仍然校验失败？

verify 只覆盖当前本地缓存；构建可能解析到另一个版本、另一个缓存，或首次从代理下载了不同内容。

企业私有模块应该关闭 GOSUMDB 吗？

通常先配置 GOPRIVATE，再按企业代理策略设置 GONOSUMDB。不要为了一个私有前缀关闭所有公共模块校验。