Go go.sum 校验不一致怎样判断代理和源码问题

我遇到过一种很容易被误判的 Go 依赖错误：同一个模块版本明明没有改过，重新执行命令却提示 go.sum 校验不一致。第一反应通常是删掉 go.sum，但这一步会把现场和可复现性一起丢掉。更稳妥的判断方式是固定“模块路径 + 版本”，分别看代理、源码直连和校验数据库给出的结果。

如果只有某个 GOPROXY 返回的内容与既有哈希不同，优先怀疑代理缓存或镜像同步；如果代理与 direct 都得到同一个新哈希，则应检查提交、标签或版本引用是否真的变了；如果只是本地项目报错，还要检查当前项目的 go.sum、GOSUMDB 和私有模块规则。

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

先不要删除 go.sum，也不要先设置 GOSUMDB=off。先确认报错对应的是 模块@版本 的 .mod 哈希还是源码 .zip 哈希，再用同一版本切换来源做对比。

我先把“校验不一致”拆成两个对象

go.sum 每行通常包含模块路径、版本和 h1: 哈希。版本后面如果带 /go.mod，校验的是该版本的模块元数据；不带时，校验的是模块源码归档中的文件内容。这两个哈希不是一回事，所以报错中的路径和后缀比“是不是同一个包”更重要。

Go 下载 .mod 或 .zip 后会计算哈希，并与主模块的 go.sum 对照。已有哈希不匹配时，工具会把它当成安全错误，不会把这份内容正常装进模块缓存。没有对应记录时，公开模块通常还会通过 checksum database 获取可信的 go.sum 行。

因此，看到下面两类信息时，排查方向不同：

先记录 GOPROXY 和校验环境

我排查时会把环境变量单独记下来，避免“终端 A 能下载，CI 终端 B 却报错”这种假对比。下面的命令只读取当前 Go 配置，不修改项目文件。

# 查看本次排查会影响模块下载和哈希校验的配置
go env GOPROXY GOSUMDB GOPRIVATE GONOPROXY GONOSUMDB GOMODCACHE

# 记录当前项目实际使用的主模块文件位置
go env GOMOD

# 只查看依赖图，不先清理 go.sum 或模块缓存
go list -m all

默认的 GOPROXY 是 https://proxy.golang.org,direct。逗号表示只有前一个来源返回 404 或 410 时才回退；竖线表示前一个来源出现更广泛的错误时也允许继续尝试。这个细节很关键：把多个代理用逗号连接，并不等于网络超时就会自动切换。

GOSUMDB 决定使用哪个 checksum database，默认是 sum.golang.org；GOPRIVATE 会影响代理和公开校验数据库的使用范围。私有模块不应该把路径发送给公共服务，但这不等于公共模块可以随意关闭哈希校验。

用同一个模块版本比较代理和源码

真正能区分“代理问题还是源码问题”的，是保持模块路径和版本完全不变，只更换来源。不要一边切换来源，一边把版本改成 @latest，否则比较对象已经变了。

# 把下面两个占位值替换成报错中的精确模块路径和版本
module_path='example.com/dependency'
module_version='v1.2.3'

# 先使用当前代理，只查询固定版本的模块信息
GOPROXY='https://proxy.example.invalid' go mod download -json "${module_path}@${module_version}"

# 再绕过代理访问源码来源；direct 仍然会遵循 Go 的模块校验规则
GOPROXY=direct go mod download -json "${module_path}@${module_version}"

# 回到默认公共代理链，观察是否能得到一致的模块元数据
GOPROXY='https://proxy.golang.org,direct' go mod download -json "${module_path}@${module_version}"

上面的 -json 输出里重点看固定版本对应的下载位置、模块目录和错误描述，不要只看命令是否返回成功。可以按下面的结果做判断：

• 只有某个代理报哈希不一致，而 direct 与公开代理能得到一致结果：优先检查该代理的缓存、同步或自建镜像配置。
• 代理和 direct 都与既有 go.sum 不一致：先确认版本标签、源码仓库和提交是否发生变化，再决定是否更新依赖记录。
• 来源结果一致，但当前项目仍报错：重点回到项目自己的 go.sum、GONOSUMDB、GOMODCACHE 和 CI 环境。

按来源修复，不用删除 go.sum 掩盖差异

如果确认只是当前依赖图缺少哈希，正常做法是让 Go 根据当前 go.mod 和源码导入关系补齐记录，再检查变更是否只包含预期模块。若确实升级了依赖版本，应把对应的 go.mod 和 go.sum 一起提交，不能只提交其中一个。

# 在确认依赖变更是预期之后，让 Go 按当前依赖图整理记录
go mod tidy

# 查看 go.mod 与 go.sum 的待提交变更，确认没有混入无关升级
git diff -- go.mod go.sum

# 只检查本地模块缓存中已有内容是否被改写；它不会替未下载内容补齐记录
go mod verify

如果问题只出现在企业代理，修复点应放在镜像同步、缓存失效和代理回退策略，而不是在每个项目里关闭校验。若模块属于私有域名，再根据组织的代理设计配置 GOPRIVATE、GONOPROXY 或 GONOSUMDB，并把配置放到开发机与 CI 都能复现的位置。

GOSUMDB=off 会放弃对未识别模块的公开校验保障，只适合非常明确、受控的特殊环境，不能作为“校验不一致”的通用修复。对公共模块来说，保留 checksum database 的一致性，才能发现代理或源站返回了不同内容。

我最后保留一张最小判断表

这类问题的关键不是“哪个命令能让它继续跑”，而是先回答“哪个来源交付了与固定版本不相同的内容”。把模块版本固定住，再分离代理、源码和本地配置三个变量，通常几分钟就能把问题从模糊的校验错误缩小到一个可修复的边界。

常见追问

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

不建议把它当第一步。这样可能得到一份新的哈希，但无法说明旧哈希为什么不一致，也会削弱变更审阅。应先固定版本并对比来源，确认依赖变化后再让 Go 生成必要记录。

GOPROXY=direct 就一定绕过所有校验吗？

不是。direct 只表示从版本控制来源获取模块，不等于关闭 checksum database。是否校验还受 GOSUMDB、GOPRIVATE 和 GONOSUMDB 影响。

go mod verify 能解决 go.sum 校验不一致吗？

它主要检查本地模块缓存中的 zip 和解压目录是否与缓存记录一致，并不是重新替你确认所有远程来源。它适合作为本地缓存排查的一环，不能代替代理与 direct 的固定版本对比。

代理返回 404 后为什么没有自动换下一个？

只有使用逗号连接时，404 或 410 才会触发常规回退；超时等其他错误通常会终止当前链。若组织网络确实需要对更多错误回退，应理解竖线配置的影响，再由代理管理员统一决定。

相关官方说明：https://go.dev/ref/mod；命令行参考：https://pkg.go.dev/cmd/go。