Go 模块校验和 mismatch 时该先检查什么

Go 报出 verifying module: checksum mismatch 时，第一步不是删掉 go.sum，也不是全局设置 GOSUMDB=off。先记下报错里的模块路径和版本，再判断冲突发生在模块的 go.mod 文件还是源码 zip。接着按“项目记录 → 本地缓存 → 代理和私有模块配置”的顺序检查，通常能分清是缓存损坏、版本内容变化，还是下载路径配置不一致。

先读 mismatch 报错里的模块和版本

错误信息中的模块路径和版本是定位坐标。例如 example.com/acme/logkit@v1.4.2，先不要把问题泛化成“Go 依赖坏了”。如果提示校验的是 go.mod，对应的是带 /go.mod 的记录；如果提示下载的 zip 与记录不符，则要关注源码包内容。两者都可能表现为 mismatch，但修复方向不同。

go.sum 每行包含模块路径、版本和 h1: 校验值。它是主模块信任记录的一部分，不是可以随手重建的临时缓存。把完整报错保存下来，并检查当前分支是否有人刚刚升级、降级或修改了 replace，这是最省时间的第一轮。

核对 go.mod、go.sum 与本地模块缓存

先看项目自身有没有未提交变化，再检查缓存中的校验记录。下面的命令只读取状态，不会主动修改依赖：

# 查看依赖声明、校验记录和模块缓存位置
git diff -- go.mod go.sum
go env GOMOD GOMODCACHE GOPROXY GOSUMDB GOPRIVATE GONOSUMDB

go mod verify

# 只针对报错模块查看下载信息，不手工改写 go.sum
go mod download -json example.com/acme/logkit@v1.4.2

go mod verify 能帮助发现模块缓存中的 zip 或展开目录与已记录哈希不一致。若项目文件没有变化、报错只在一台机器出现，且缓存位置明确，才有理由怀疑本地缓存损坏。此时可以先保留终端输出，再执行 go clean -modcache 重试；不要把清缓存当成每次 mismatch 的默认答案。

再检查 GOPROXY、GOSUMDB 与私有模块边界

同一版本的模块内容如果经过不同代理路径取得，排查时要看 GOPROXY。公开模块缺少本地记录时，Go 通常会通过校验和数据库核实并补充 go.sum；而私有模块不应发送到公共代理或公共校验和数据库。把公司模块前缀写入 GOPRIVATE，必要时再细化 GONOPROXY、GONOSUMDB，比关闭全局校验更安全。

# 只把公司模块前缀划为私有，公开依赖仍保持校验
go env -w GOPRIVATE=git.example.com/acme/*
go env -w GONOSUMDB=git.example.com/acme/*

# 检查实际使用的代理和校验数据库
go env GOPROXY GOSUMDB GOPRIVATE GONOPROXY GONOSUMDB

如果是代理返回了与已记录哈希不同的内容，不要直接接受新哈希。先换到可信的代理或直接向维护者确认该版本是否被重新打包；模块版本内容发生变化时，继续使用原版本可能破坏可复现构建。

按原因选择恢复动作

修复后用同一个模块路径和版本重新下载，再运行 go mod tidy、目标测试和 CI。若是依赖发布方重新打了同名版本，应优先换到新的明确版本，而不是把当前机器算出的哈希覆盖进仓库。这样留下的变更能解释“为什么改”，也方便其他开发者复查。

常见问题

删掉 go.sum 后重新生成可以吗？

不建议作为第一步。这样会丢失冲突证据，还可能把错误代理返回的内容重新写入记录。先定位模块、版本和来源。

设置 GOSUMDB=off 能解决 mismatch 吗？

它可能绕过部分校验，但会降低公开依赖的完整性保障，不能修复已经存在的内容不一致。私有模块应使用 GOPRIVATE 等精确配置。

go mod tidy 后仍然失败怎么办？

回到报错中的具体版本，比较 go.sum 的两类记录，检查代理和缓存；如果依赖内容确实变化，选择新的版本并提交可解释的 go.mod 与 go.sum 变更。