go mod download -dirty 或 go clean -modcache 可临时绕过 checksum 错误，但根本解法是检查 go.sum 中被篡改或错配的模块校验和；replace 与 require 配合可使本地修改被正确签名，确保构建可重现。
直接说结论：go mod download -dirty 或 go clean -modcache 后重试，基本能绕过 checksum 验证失败导致的构建中断；但真正要稳，得查 go.sum 里哪一行被篡改或版本错配——这不是网络问题，是模块完整性校验在“打脸”你本地的修改。
为什么 checksum error 不是网络抽风，而是 go.sum 在报警
Go 模块下载后会生成 go.sum 文件，记录每个模块路径+版本+对应 .zip 的 SHA256 值。一旦你手动改过某个依赖的源码（比如 patch 了 vendor/ 下的代码）、用 replace 指向了本地未 commit 的分支、或从非官方 proxy 拉了被二次打包的包，下次 go build 或 go mod tidy 就会比对失败，报类似：
verifying github.com/some/pkg@v1.2.3: checksum mismatch downloaded: h1:abc123... go.sum: h1:def456...
这不是缓存脏了，是 Go 明确告诉你：“你当前用的代码，和上次声明的指纹对不上”。
- 别急着删
go.sum—— 它不是日志，是契约 -
go mod verify可快速定位哪个模块校验失败 - 如果确认是自己改过且想保留，就运行
go mod sum重写校验和（仅限开发环境）
go mod download -dirty 是什么偏方？怎么用才不埋雷
go mod download -dirty 的作用是：跳过所有 checksum 校验，强制把模块 zip 解压进 $GOMODCACHE。它适合临时调试，比如你正在 fork 并 patch 一个库，还没推远程，又不想每次改完都 go mod edit -replace。
立即学习“go语言免费学习笔记（深入）”；
- 执行前先
git status确认你改的是谁，避免误伤其他依赖 - 执行后必须立刻
go mod sum，否则下次别人拉你代码会直接失败 - CI/CD 流水线严禁使用该 flag，它会让构建失去可重现性
replace + require 组合拳，才是解决“私有修改冲突”的正解
当你必须长期基于某个包的定制版开发（比如打了安全补丁），正确做法不是删 go.sum，而是用 replace 显式接管，并让 require 锁定语义版本：
require github.com/xxx/pkg v1.5.0 replace github.com/xxx/pkg => ./internal/patched-pkg
这时 go.sum 会为 ./internal/patched-pkg 生成本地路径校验和，不再校验原始 URL。关键点：
-
replace路径必须是绝对路径或相对于go.mod的相对路径 - 如果
./internal/patched-pkg是 git 仓库，确保它有 tag（如v1.5.0-patch1），否则go list -m无法识别版本 - 多人协作时，
replace行不能只写在某人本地的go.mod里，必须提交到主干
checksum error 的本质，是 Go 在坚持“所见即所得”。你改了代码却不更新指纹，就像签合同后手写涂改金额却不按手印——系统当然拒绝背书。最省事的偏方治标，而理解 go.sum 和 replace 的协作逻辑，才能让每次 go build 都心里踏实。
