Go Modules 的版本校验由 go.sum 文件和 GOSUMDB 机制原生实现，go.sum 是工具链内置的只读校验文件而非可替换库；迁移需清理缓存、重置信任链并适配私有场景，常见错误包括误删、手动编辑或试图用第三方工具替代校验。
Go Modules 的版本校验不靠独立“库”迁移，而是靠 go.sum 文件 + GOSUMDB 机制原生实现；所谓“迁移”，本质是清理旧校验残留、重置校验信任链、适配私有场景。
go.sum 不是可替换的第三方库，而是 Go 工具链内置的校验层
很多人误以为 go.sum 是某个可升级或替换的校验库（比如类似 checksum 或 gosum），其实它只是 Go 编译器和 go 命令在执行 go build、go get、go mod tidy 时自动生成并校验的文本文件。它没有源码、不参与编译、也不提供 API。
常见错误现象：
- 删掉
go.sum后go build报checksum mismatch—— 实际是本地缓存模块内容与远程 tag 哈希不一致，不是文件丢失导致 - 手动编辑
go.sum添加哈希值 —— 下次go mod tidy会直接覆盖，且可能因格式错位引发解析失败 - 试图用
go get github.com/xxx/go-sum-checker替代校验 —— 完全没必要，Go 工具链已强制内置
从 GOPATH 时代迁移到 Go Modules 时，go.sum 校验常卡在哪儿
旧项目（用 dep/glide）迁移后首次 go mod tidy 失败，多数不是 go.sum 本身问题，而是校验触发了路径/版本/网络三重冲突：
立即学习“go语言免费学习笔记（深入）”；
-
gopkg.in/yaml.v2这类重定向 import 在go.mod中没用replace修正，导致 Go 尝试从gopkg.in拉取，但该域名响应慢或返回非标准 tag，go.sum写入失败 - 本地
$GOPATH/pkg/mod缓存里存着旧版模块（比如v1.2.0），而远程仓库已删该 tag，go mod tidy拉不到，又拒绝用缓存内容生成go.sum - CI 环境未设
GOPROXY=direct，但GOSUMDB默认连国外服务器校验，超时即中断，报错像failed to fetch checksums
实操建议：
- 先清缓存：
go clean -modcache（别只删go.sum） - 再显式初始化：
go mod init github.com/your-org/your-repo（避免路径推断出错） - 对重定向路径，立刻加
replace：replace gopkg.in/yaml.v2 => gopkg.in/yaml.v2 v2.4.0 - CI 脚本开头加：
go env -w GOPROXY=https://goproxy.cn,direct GOSUMDB=off（仅限可信内网环境）
私有模块和跳过校验的正确姿势
企业内网项目常需绕过公有校验，但 GOSUMDB=off 是全局关闭，风险高；更安全的做法是精准控制范围：
- 用
GOPRIVATE标记私有域名：go env -w GOPRIVATE="git.internal.company.com,github.com/my-team" - 这样 Go 会自动对匹配路径禁用
GOSUMDB和GOPROXY，无需手动关总开关 - 若某模块确实要临时跳过校验（如调试中 fork 的分支），可用
go get -insecure github.com/fork/repo@dev-branch，但仅限本地，切勿提交到 CI -
go mod verify命令可手动触发全量校验，但它不修复问题，只报错；修复必须靠go mod tidy重拉 + 清缓存
真正容易被忽略的是：校验失败时，Go 不会告诉你哪个模块哈希不匹配，只报最后一行出错模块。得配合 go list -m all | grep -v 'indirect' 逐个检查，或用 go mod graph | grep 'broken-module' 定位上游依赖源。
