checksum mismatch 根本原因是 sum.golang.org 记录的哈希值与本地下载内容不一致，主因包括作者强制覆盖 tag、代理缓存污染或本地模块缓存损坏；应先执行 go clean -modcache 并删 go.sum，再用 go mod tidy 重建，或临时设 goproxy=direct 验证是否为镜像问题。
为什么 go mod download 会报 checksum mismatch 错误
根本原因是 Go 的校验和数据库（sum.golang.org）记录的模块哈希值，和本地实际下载到的代码不一致。不是网络问题，也不是你改了代码——而是模块发布者撤回/覆盖了已发布的版本（比如用 git push --force 修改了 tag），或者你被代理/镜像源劫持、缓存了脏数据。
快速验证是否是镜像源导致的问题
先绕过所有代理和 GOPROXY，直连官方源验证：
- 临时清空代理：
GOPROXY=direct go mod download - 如果成功，说明你配置的镜像（如
https://goproxy.cn或https://proxy.golang.org）缓存了旧版或被污染 - 检查当前生效的代理：
go env GOPROXY，注意off和direct的区别：前者禁用所有代理，后者仅跳过 proxy 但仍走 checksum 校验
如何安全地跳过某模块的 checksum 校验
仅限调试或内部可信模块，生产环境慎用。Go 不允许全局禁用校验，但可对特定模块豁免：
- 在
go.mod同级目录运行：go env -w GOSUMDB=off—— 全局关闭（不推荐） - 更安全的做法：用
GOSUMDB=off作为前缀执行单次命令，例如：GOSUMDB=off go mod download github.com/some/internal/pkg@v1.2.3 - 若只想跳过某个模块，且该模块托管在私有 Git 服务器上，可在
go.mod中显式 replace 并指定 commit hash：replace github.com/some/pkg => git.example.com/some/pkg v0.0.0-20230101000000-abc123def456
遇到 checksum mismatch 时最常被忽略的细节
很多人重试多次失败后直接删 go.sum，这是危险操作。真正该检查的是：
-
go.sum里对应行的哈希值是否和sum.golang.org上查到的一致（访问https://sum.golang.org/lookup/github.com/user/repo@v1.2.3） - 模块路径是否带了意外的
/v2或/v3后缀，导致 Go 解析出错版本 - 本地
go.mod中写的是github.com/user/repo v1.2.3，但该 tag 实际指向的 commit 在 GitHub 上已被 force-push 覆盖过
这种情况下，唯一可靠的做法是联系模块维护者确认 tag 状态，或切换到明确 commit 的 pseudo-version（如 v1.2.3-0.20230101000000-abc123def456）。
