go mod download 报 checksum mismatch 错误表明本地 go.sum 记录的哈希值与实际模块内容不一致，常见于 tag 重推、代理切换或手动修改 go.sum；应先 clean -modcache 再重新下载，必要时用 go mod verify 排查缺失或错误校验值。
go mod download 报 checksum mismatch 错误
这是 Go 模块校验失败最直接的表现，说明本地 go.sum 文件记录的哈希值与当前从代理或源站拉下来的模块内容不一致。不是网络问题，也不是权限问题，而是 Go 拒绝加载“被篡改”或“版本漂移”的包。
常见触发场景：模块作者重推了同一 tag（比如 v1.2.3）但内容变了；你切换了 GOPROXY（比如从官方 proxy.golang.org 切到私有代理），而两个源缓存的模块版本不一致；或者本地 go.sum 被手动修改过。
- 先确认出错的具体模块和版本：
go mod download或go build报错里会带完整路径，例如github.com/sirupsen/logrus v1.9.0: checksum mismatch - 运行
go clean -modcache清掉本地模块缓存——别跳这步，否则重拉还是旧缓存 - 再执行
go mod download，让 Go 重新拉取并生成新校验值 - 如果仍失败，临时禁用校验验证是否是代理/网络导致：
GOPROXY=direct go mod download，但仅用于排查，不建议长期使用
go.sum 文件里某行 hash 值明显不对
go.sum 是纯文本，每行格式为 module path version h1:xxx，其中 h1: 后是 SHA-256 哈希。如果某行末尾 hash 长度不对（比如只有 32 位）、含非法字符、或和实际模块内容明显不符（可通过 go mod verify 复现），说明该行已失效。
- 不要手动编辑
go.sum中的 hash 值——Go 不认你手算的 - 删掉整行后运行
go mod tidy，Go 会自动补上正确 hash - 如果模块是私有库且没配
replace或goproxy，go mod tidy可能根本拉不到，这时得先确保git能 clone 通，再重试 - 注意：
go.sum中同一模块可能有多行（不同子模块或不同校验算法），删错行会导致后续go build再次报 mismatch
CI 环境中反复出现 checksum mismatch
CI 构建失败常因环境不一致放大校验问题：镜像里缓存了旧模块、GOPROXY 配置漂移、或构建前没清 go/pkg/mod。这不是本地开发者的锅，是流水线配置缺陷。
立即学习“go语言免费学习笔记（深入）”；
- 在 CI 脚本开头加
go clean -modcache，强制每次从零拉取 - 显式锁定 GOPROXY：
GOPROXY=https://proxy.golang.org,direct，避免依赖环境默认值 - 检查是否用了
go mod vendor但没提交vendor/modules.txt——它和go.sum是两套校验机制，混用容易冲突 - 若用私有代理（如 Athens），确认其缓存策略是否允许覆盖同 tag 的模块；有些代理默认禁止，需手动 purge
go mod verify 提示 missing or wrong checksum
go mod verify 是离线校验命令，只读本地缓存和 go.sum。它报错说明：要么模块根本没下载（missing），要么已下载但 hash 对不上（wrong）。这个命令不联网，所以结果稳定，适合做构建前自检。
- 运行
go mod verify后如果提示missing，说明go.sum里写了某模块但本地没对应缓存，执行go mod download即可补全 - 如果提示
wrong，优先怀疑模块源端被修改——尤其是未发布正式版的master或main分支依赖，这类 commit-hash 依赖极不稳定 - 对高稳定性要求的项目，应避免直接依赖
github.com/user/repo v0.0.0-20230101000000-abcdef123456这类时间戳伪版本，改用打 tag 的语义化版本
真正麻烦的是跨团队协作时，有人 go mod tidy 后提交了新 go.sum，但没同步更新 go.mod 里的依赖版本，导致其他人 go build 时拉到旧版模块却套用新版 hash。这种隐性不一致，比报错更难定位。
