checksum mismatch不是网络问题，因go已成功下载模块，仅校验和与go.sum记录不符；主因是本地缓存损坏、代理返回污染包或上游强制覆盖tag。
直接清理缓存 + 重生成 go.sum 是最可靠解法，别试图修单行校验和。
为什么 checksum mismatch 不是网络问题
错误信息里出现 verifying github.com/xxx@v1.2.3: checksum mismatch，说明 Go 已成功下载模块，只是内容和 go.sum 里存的哈希对不上。它和 GOPROXY 配错、连不上 GitHub 完全无关——是本地缓存、代理返回污染包、或上游强制覆盖 tag 导致的校验冲突。
常见现象包括：
- 同一命令在不同机器上表现不一致（环境差异）
- 删掉
go.sum后go mod tidy又立刻报新 mismatch（缓存残留） - CI 构建失败但本地能过（CI 环境用了旧缓存或不同代理）
清理缓存并重建依赖链
执行以下三步，90% 的校验和问题会消失：
- 运行
go clean -modcache—— 清空$GOPATH/pkg/mod/cache全部内容，不碰go.mod和代码 - 删除项目根目录下的
go.sum（推荐，避免旧记录干扰） - 再执行
go mod tidy或go get -u ./...，让 Go 重新下载、计算并写入新校验和
注意：go clean -modcache 是整仓清理，别手动删子目录——部分损坏包可能藏在深层路径里，只清一部分反而更难排查。
确认是否是代理污染导致
国内常用代理如 https://goproxy.cn 有时会同步滞后或缓存了被作者撤回的版本。临时绕过代理验证：
- Linux/macOS：运行
export GOPROXY=direct - Windows：运行
set GOPROXY=direct - 再跑一次
go mod tidy
如果 direct 下成功，说明代理返回的内容与官方不一致。可改用 https://proxy.golang.org，或配置多源兜底：GOPROXY=https://goproxy.cn,https://proxy.golang.org,direct。
企业内网 proxy 若重写 zip 包（比如注入 license header），也会必然触发 mismatch——这种情况下必须联系 infra 团队修复代理逻辑，不能靠客户端 workaround。
遇到作者 force push tag 怎么办
这是最隐蔽的情况：某人把 v1.2.3 对应的代码库内容直接 git push --force 覆盖了，而 Go 的校验和是按 zip 包算的，内容一变就对不上。此时 go.sum 里存的是旧哈希，但新 zip 已不可逆。
判断方法：
- 查
go.sum中该模块对应行，记下旧 hash - 运行
go mod download -json github.com/xxx@v1.2.3，看它实际指向哪个 commit - 若 commit hash 和你预期不符，基本确认是 tag 被篡改
唯一稳妥办法是放弃 tag，改用 commit hash 锁定：go get github.com/xxx@a1b2c3d。这样绕过语义化版本，直接绑定不可变提交。
这种 case 很难自动化检测，也容易被忽略——尤其当团队共用一个私有模块且发布流程不规范时，建议对关键依赖启用 GONOSUMDB 并配合内部镜像签名机制。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
