go.sum校验失败时应先执行go clean -modcache清理全局缓存并删除go.sum，再运行go mod tidy或go get -u重建校验；若ci失败需检查goproxy配置，作者强制覆盖tag则须改用commit hash锁定版本。
go.sum校验失败时，别急着改代码，先清缓存
checksum mismatch 不是你的代码写错了，而是 Go 拿到的模块内容和 go.sum 里记的哈希对不上。最常见原因是本地模块缓存（$GOPATH/pkg/mod/cache）里混进了损坏或过期的包——手动删子目录没用，必须整仓清理。
- 运行
go clean -modcache，它只清模块缓存，不影响go.mod和你自己的代码 - 顺手删掉项目根目录下的
go.sum（推荐，避免旧记录干扰重建） - 再跑
go mod tidy或go get -u，让 Go 重新下载、计算并写入新哈希
CI 构建失败，大概率是 GOPROXY 配置漏了
Dockerfile 或 GitHub Actions 里只写 RUN go version 是不够的。没有显式设代理，CI 环境默认走 https://proxy.golang.org，而国内节点偶尔同步滞后或返回污染包，直接触发校验失败。
- 在构建阶段开头加两行：
go env -w GOPROXY=https://goproxy.cn,https://proxy.golang.org,direct和go env -w GOSUMDB=off（后者仅限私有模块或离线环境） - GitHub Actions 中，
actions/setup-go后立即加run: go env -w GOPROXY=...，别依赖 job-level 环境变量继承 - 如果用 Docker，把这两条
go env -w放进Dockerfile的RUN指令里，确保每层构建都生效
代理没问题？检查是不是作者 force push 覆盖了 tag
有些维护者会 git push --force 覆盖已发布的 v1.2.3 tag，Go 的 checksum 是按 zip 包算的，内容一变哈希就崩。这时 go.sum 里存的是旧哈希，但新 zip 已不可逆。
- 查
go.sum里报错那行，找到对应模块和版本，执行go mod download -json <module>@<version></version></module>看它实际指向哪个 commit - 如果 commit hash 变了，说明 tag 被动过；唯一靠谱办法是放弃 tag，改用 commit 锁定：
go get <module>@a1b2c3d</module> - 别信
go mod edit -replace临时绕过——它不解决校验问题，go build仍会校验原始模块
多 module 项目里，go.sum 不一致容易被忽略
monorepo 里每个子 module 都有自己的 go.mod 和 go.sum，但很多人只在根目录配一份 .golangci.yml 或只清理根目录缓存，导致子 module 的校验状态脱节。
- CI 脚本里，对每个需要构建的子 module 目录，单独执行
cd ./cmd/api && go mod tidy类操作 - 清理缓存不能只跑一次
go clean -modcache，它作用于全局缓存，但不同 module 可能依赖不同版本，需确保所有 module 都触发重下载 - Git 提交前，用
go list -m -f '{{.Path}} {{.Version}}' all检查各 module 解析出的实际版本是否预期一致
真正麻烦的不是报错本身，而是校验失败可能藏在间接依赖里——go.sum 里某一行哈希不对，但报错却出现在完全无关的 go build 步骤。遇到这种，直接从 go mod graph 找出该模块的上游路径，比盲猜快得多。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
