go.sum校验失败本质是哈希值不匹配而非版本冲突，常见于本地修改依赖未更新go.sum、多人协作误删重生成或私有模块校验逻辑不一致；修复需确认修改必要性，用replace临时调试或go mod tidy重新计算校验和，严禁手动编辑go.sum。
go.sum 校验失败不是版本冲突，是校验和不匹配
高频重构时 go build 或 go test 突然报 verifying github.com/xxx@v1.2.3: checksum mismatch，本质不是“依赖版本冲突”，而是 go.sum 中记录的哈希值与当前下载内容不一致。常见于：本地改过依赖源码但没更新 go.sum、多人协作时有人删了 go.sum 后重生成、私有模块未配置 GONOSUMDB 导致校验跳过逻辑不一致。
修复只需两步：
- 确认是否真需修改依赖：若只是临时调试，用
replace指向本地路径，避免触碰go.sum - 若已修改并提交代码，运行
go mod tidy -compat=1.17（或匹配项目最低 Go 版本），它会重新计算所有校验和并更新go.sum - 切勿手动编辑
go.sum—— 它是自动生成的锁定文件，手改极易引入空格、换行或顺序错误
replace 在重构中被误用于“绕过校验”，反而放大问题
重构期间常有人加 replace github.com/a/b => ./local-fix 临时调试，但忘了 CI 构建时该路径不存在，导致 go build 直接失败。更隐蔽的问题是：同一 replace 被多个分支各自添加，合并后形成冲突，而 go mod tidy 不会报错，只静默保留第一个。
安全用法要点：
- 本地调试用
replace后，务必在.gitignore中排除./local-fix目录，防止误提交 - CI 流水线中设置环境变量
GOPROXY=direct+GONOSUMDB=*.internal（按实际私有域名调整），避免因代理缓存导致校验不一致 - 所有
replace行末尾加注释说明用途和预期移除时间，例如：// replace for fix-xxx until v1.4.0 released, remove after 2026-09-01
go mod tidy 在重构中会“自动降级”，必须配合 go list -m all 验证
重构时删掉某个旧功能模块，执行 go mod tidy 后发现某依赖版本反而变低了，甚至回退到 v0.0.0-incompatible。这是因为 MVS 算法重新计算最小可行集，而你删掉的模块原本是唯一 require 高版本的“锚点”。
操作前必做验证：
- 运行
go list -m all | grep target-module记下当前版本 - 删代码后，先跑
go mod tidy，再立刻执行go list -m all | grep target-module对比 - 若版本下降且业务需要高版本，立即补上
go get target-module@vX.Y.Z，让require显式存在 - 避免依赖
go.mod中残留的// indirect行——它们不可靠，go mod tidy可能随时删掉
多模块工作区（go work）在重构中反而增加校验复杂度
用 go work init ./a ./b 管理子模块时，go.sum 会拆成每个子模块自己的 go.sum + 工作区顶层一个 go.work.sum。重构中移动包路径或合并模块，容易漏掉某个子模块的 go.sum 更新，导致本地构建通过、CI 失败。
关键检查点：
- 每次修改
go.work后，进每个子模块目录单独跑一次go mod tidy，再回到根目录跑go work sync -
go.work.sum不应手动编辑；若校验失败，删掉它再运行go work sync重建 - 禁止在子模块的
go.mod中写replace—— 它只对本模块生效，工作区其他模块仍可能拉取原始版本，造成类型不匹配
go.sum 是增量更新，而 CI 拉的是干净 workspace，从头 go mod download，此时任何未显式声明的版本约束都会暴露出来。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
