go.sum校验失败会直接中断依赖拉取，因go在下载后立即比对哈希值，不匹配则硬性拒绝；常见原因包括上游强制覆盖tag、代理返回旧包、本地缓存污染或zip内容变更。
go mod download 或 go build 卡在 checksum mismatch，不是网络问题，而是校验失败导致的拉取中断——必须处理 go.sum 与实际下载内容的哈希不一致，不能只调 GOPROXY。
为什么 go.sum 校验失败会直接中断依赖拉取
Go 在下载模块后，会立即用 go.sum 中记录的哈希值验证 zip 包和 go.mod 文件内容。一旦不匹配，go 命令会立刻终止操作并报错 verifying github.com/xxx@v1.2.3: checksum mismatch，不会继续后续步骤。这不是警告，是硬性拒绝。
常见诱因包括：
- 上游强制覆盖了同名 tag（
git tag -f v1.2.3），但没改 commit； - 模块发布者重新打包了 zip（比如调整了 .gitignore 或构建脚本）；
- 你本地缓存被污染，或之前用不同 Go 版本下载过同一版本；
- 用了代理但代理返回了缓存旧包，而
go.sum记的是新包哈希。
如何安全更新 go.sum 中错误的哈希值
别删 go.sum，也别加 -mod=mod 跳过校验——这会让项目失去完整性保障。正确做法是让 Go 工具链重算并写入可信哈希：
- 先确认当前解析出的实际源地址：
go list -m -json github.com/xxx/pkg@v1.2.3，看Origin.URL和Version是否是你预期的； - 手动访问该 URL 对应的 archive 链接（如
https://github.com/xxx/pkg/archive/v1.2.3.zip），下载 zip 并运行：shasum -a 256 v1.2.3.zip | awk '{print $1}' | xxd -r -p | base64（注意：Go 存的是 base64 编码的 SHA256，不是 hex）； - 如果手动算出的哈希与
go.sum中的h1:xxx不一致，且你信任这个新包，就执行：go mod download github.com/xxx/pkg@v1.2.3； - Go 会重新下载、校验、写入新哈希到
go.sum，且只更新这一行，不影响其他依赖。
GOPROXY=off 时 GOSUMDB 必须同步设为 off
如果你在局域网或离线环境设了 GOPROXY=off，但忘了关 GOSUMDB，go mod download 仍会尝试连接 sum.golang.org，结果就是卡住或报 dial tcp: i/o timeout。
必须成对设置：
go env -w GOPROXY=offgo env -w GOSUMDB=off- 验证生效：
go env GOPROXY GOSUMDB应输出off off
注意：GOSUMDB=off 意味着完全跳过校验，仅适用于可信内网环境；若用私有代理，可设 GOSUMDB="sum.golang.org+http://your-proxy/sumdb"。
go.sum 被意外修改后最该检查的三件事
提交或 CI 失败前，快速定位是否是 go.sum 引发的问题：
- 执行
go list -m all | wc -l，对比上一次成功构建时的模块总数，突增说明有新依赖未被校验通过； - 搜索
go.sum中是否有重复路径+版本（比如两行都含github.com/sirupsen/logrus v1.9.0），Go 不允许重复； - 检查
go.sum最后几行是否含/go.mod h1:条目缺失——每个模块至少要有主包哈希和go.mod哈希两行，少一行就会校验失败。
真正麻烦的从来不是下载慢，而是哈希校验失败后没人知道该信哪一端——你得自己比对来源、确认变更意图，再决定是重写 go.sum 还是降级版本。
