checksum mismatch 是模块校验失败，源于 go.sum 记录的哈希值与实际模块 zip 包内容不匹配，主因包括本地缓存损坏、代理返回污染包或上游强制覆盖 tag；推荐先执行 go clean -modcache 清理缓存并删除 go.sum，再用 go mod tidy 重建。
校验和冲突不是网络问题，也不是权限问题，而是本地缓存、代理污染或上游篡改导致的哈希不匹配。直接删 go.sum 和清理缓存，再重建依赖，能解决 90% 的情况。
为什么 checksum mismatch 总是反复出现
错误信息里那串 h1:xxx= 是 Go 对模块 zip 包内容计算出的 SHA256 哈希。只要包内容变了（哪怕只是作者 git push --force 覆盖了 tag），哈希就对不上。go.sum 里存的是旧哈希，新下载的包却是新内容，冲突就触发了。
- 常见诱因包括：本地
$GOPATH/pkg/mod/cache混入损坏包 - 国内代理（如
goproxy.cn）节点缓存滞后或被污染 - 企业内网 proxy 在 zip 包里注入 header 或 license，必然改哈希
- 模块作者用同一 tag 发布不同代码（即 “tag retraction”）
清理缓存 + 重建 go.sum 是最稳操作
别只删 go.sum，也别手动删 cache 里的某个子目录——整仓清理才可靠。
- 执行
go clean -modcache：清空所有已缓存模块，不影响go.mod和你的源码 - 删除项目根目录下的
go.sum文件（推荐，避免旧记录干扰） - 运行
go mod tidy或go get -u ./...：重新下载、校验、写入新go.sum
注意：go clean -modcache 不会删你写的代码，也不影响 go.mod 中声明的版本约束。
立即学习“go语言免费学习笔记（深入）”；
怀疑代理有问题？临时切 direct 验证
如果清理后仍报错，大概率是代理返回了与官方不一致的内容。
- Linux/macOS：执行
export GOPROXY=direct - Windows：执行
set GOPROXY=direct - 再跑一次
go get -u xxx，看是否成功
若 direct 成功，说明代理不可信。可换用 GOPROXY=https://proxy.golang.org,direct，让失败时自动回退到直连。
作者改了 tag 却没升版本？只能锁定 commit
这是最棘手的情况：v1.2.3 对应的代码被覆盖了，但 go.sum 还记着旧哈希，而新 zip 已不可逆。
- 查
go.sum中该模块对应行，确认哈希不匹配 - 运行
go mod download -json xxx@v1.2.3，看它实际指向哪个 commit - 若确认是作者违规操作，放弃 tag，改用 commit hash：
go get xxx@a1b2c3d
commit hash 锁定绕过了 tag 校验，但代价是失去语义化版本的可读性——这点容易被忽略，尤其在团队协作中。
