Go go mod verify 和 go.sum mismatch 分别验证什么

CI 里看到 go: verifying module: checksum mismatch，紧接着本地又有人建议执行 go mod verify，很容易把两个现象当成同一件事。它们的校验对象其实不同：go mod verify 主要检查本机模块下载缓存里的源码是否被改过；go.sum mismatch 则是在下载或读取模块校验记录时，发现实际内容与期望哈希对不上。

先看清两个错误分别在校验什么

模块下载成功后，Go 会把版本内容放进本地模块缓存，同时依据 go.sum 中的记录确认内容。go mod verify 复查的是当前模块依赖对应的本地缓存副本：如果缓存中的源码目录或下载内容与最初记录不一致，它会列出被改动的模块并以非零状态退出。

而 mismatch 通常发生在 Go 试图取得某个版本的 .zip 或 go.mod 哈希时。实际哈希与 go.sum、校验数据库或下载链路提供的期望值冲突，就会停止继续使用该版本。这个错误说明“当前内容不能被信任”，不等价于“本地缓存目录一定被手改过”。

用文件和缓存边界复盘 mismatch 的来源

排查时可按下面的对照表缩小范围。尤其要注意：go.sum 是期望记录，不是缓存内容本身；它通常应与项目一起提交，供另一台机器复现相同依赖校验。

先确认模块路径和版本，再看环境配置，不要一上来执行 go clean -modcache。清缓存可以排除损坏的本地副本，却不能修复代理上传了错误内容、私有模块没有正确绕过校验，或上游同一版本内容发生变化的问题。

一组命令把问题定位到缓存、来源还是配置

# 查看当前模块下载与校验策略，避免把网络配置误判成代码问题
go env GOPATH GOMODCACHE GOPROXY GOSUMDB GOPRIVATE

# 复查当前依赖对应的本地缓存是否仍保持原始内容
go mod verify

# 只针对怀疑的模块版本重新取得下载信息，不直接修改业务代码
go mod download -json example.com/tracekit@v1.4.2

如果 go mod verify 失败而重新下载后恢复，重点看本机缓存目录是否被构建脚本复用或改写。如果 go mod download 仍报 mismatch，则把注意力转到代理、校验数据库和该版本的实际发布内容。私有模块场景要确认 GOPRIVATE 覆盖了正确的模块路径；公开模块则不应随意关闭 GOSUMDB 来“绕过”错误。

修复时保留可追溯的校验链

确认依赖来源可信后，才考虑清理本地缓存并重新下载；如果只是项目新增了合法依赖，让 Go 通过正常的 go get 或构建流程更新 go.sum，然后把变更与 go.mod 一起审查提交。若同一版本在不同代理返回不同哈希，不要手工改成“能通过”的那一行，应先核对版本发布源和代理镜像。

一句话记忆：go mod verify 问的是“我这台机器缓存里的模块有没有被改动”，go.sum mismatch 问的是“当前拿到的模块版本内容，是否与可信的哈希记录一致”。先分清这两个问题，修复动作就不会误伤依赖锁定。

常见问题

go mod verify 会检查 go.mod 文件本身吗？

它围绕本地下载的依赖内容进行复核，结果不能替代对主模块 go.mod 变更的代码审查。

删除 go.sum 能解决 checksum mismatch 吗？

不应作为默认修复。删除记录可能掩盖错误来源；先确认模块版本、代理响应和私有模块配置，再决定是否重新生成可信记录。

go mod verify 失败后应该立刻清空缓存吗？

先检查缓存是否被脚本或工具改写。只有确认本地副本损坏且来源可信时，清理并重新下载才有针对性。