checksum mismatch错误根本原因是模块校验机制发现本地缓存zip包哈希值与go.sum记录不一致，主因包括作者重写tag、go.sum未更新或间接模块被替换但checksum未同步，非网络传输损坏所致。
为什么 go mod download 会报 checksum mismatch 错误
根本原因是 Go 的模块校验机制发现本地缓存的模块 zip 包哈希值，和 go.sum 文件中记录的不一致。这通常不是网络传输损坏导致的，而是：模块作者重写了 tag（比如 v1.2.0 指向了新 commit）、你本地 go.sum 还没更新、或依赖的间接模块被替换成 fork 版但没同步 checksum。
常见错误信息形如：verifying github.com/some/pkg@v1.2.0: checksum mismatch，后面跟着两个不同 hash —— 一个是预期的，一个是实际下载到的。
- 别直接删
go.sum，那会让所有模块校验失效，后续构建不可复现 - 也别手动改
go.sum里的 hash，Go 工具链不会认，下次go mod tidy还会覆盖 - 如果模块是私有仓库，确认 GOPRIVATE 是否已正确配置，否则 Go 仍会尝试走 proxy 并校验公共 checksum
用 go mod download -dirty 快速绕过校验（仅限调试）
这个 flag 不是“跳过校验”，而是允许使用本地未提交的修改版本（即 git status 有变更时），同时跳过 checksum 校验。它只在你明确知道模块源码已被本地修改、且不想提交/打 tag 的临时场景下有用。
执行前确保当前模块目录干净，否则 -dirty 会失败。更安全的做法是：
立即学习“go语言免费学习笔记（深入）”；
- 先运行
go mod edit -replace=github.com/some/pkg=../some-pkg指向本地路径 - 再运行
go mod download，此时 Go 不会校验本地路径模块的 checksum - 调试完记得删掉
-replace，再go mod tidy恢复线上依赖
修复 go.sum 的标准流程
核心原则：让 go.sum 反映当前实际使用的模块版本及其真实 hash。不要手写，全交给 Go 工具链。
- 删掉出错模块在
go.sum中的两行（module@version和module@version/go.mod） - 运行
go mod download github.com/some/pkg@v1.2.0，触发重新下载并写入新 hash - 运行
go mod tidy，补全缺失的间接依赖并清理冗余项 - 如果多个模块同时出问题，优先处理直接依赖；间接依赖的 checksum 通常会在
tidy时自动修正
注意：若模块已从公共 registry 移除（如作者删库），Go 会 fallback 到 proxy（如 proxy.golang.org），但 checksum 仍需匹配。此时应确认是否真要继续用该版本，还是升级/降级到可用版本。
私有模块与 GOPROXY 配合避免 checksum 冲突
私有模块默认会被 Go 当作公共模块处理，走代理下载并校验公开 checksum，结果必然 mismatch。关键在于让 Go 完全跳过 proxy 和校验。
- 设置
GOPRIVATE=git.example.com/myorg/*（支持通配符），告诉 Go 这些域名下的模块不走 proxy - 确保
GOPROXY不包含这些域名，例如设为GOPROXY=https://proxy.golang.org,direct - 若用自建 proxy（如 Athens），需单独配置其信任私有源，否则它返回的 zip 仍可能带错 hash
- 团队内统一
go env -w GOPRIVATE，避免有人漏配导致 CI 失败
checksum mismatch 看似是校验失败，本质是模块来源和声明不一致。修复重点不在“怎么跳过”，而在“让声明和实际来源对齐”——无论是通过更新 go.sum、调整 GOPROXY，还是显式 -replace。最容易被忽略的是：出错模块可能是间接依赖，而 go list -m all 才能看清它真正来自哪个上游模块。
