go.sum校验失败根本原因是zip包哈希不匹配，主因是模块路径冲突、代理污染或作者强制覆盖tag；应先用go mod download -json和goproxy=direct定位问题层，再针对性解决。
Go 多项目共用模块时出现校验失败（checksum mismatch），根本不是缓存或网络问题，而是模块路径、代理响应、tag 篡改三者之一在作祟；清理缓存只是表层操作，不查清来源就重跑 go mod tidy 只会反复失败。
为什么 go.sum 里 hash 对不上实际下载内容
Go 的校验机制只认 zip 包哈希，不关心 Git commit 或 tag 名字。一旦模块作者用 git push --force 覆盖了已发布的 v1.2.3 tag，或者企业 proxy 在 zip 包里注入 license header，哈希必然不匹配。
-
go.sum记录的是当时下载的 zip 哈希，不是源码哈希 - 同一 tag 下不同时间下载，可能拿到不同 zip（尤其国内代理同步滞后）
- 私有仓库若没配
GOPRIVATE，go 会走 proxy 下载，而 proxy 返回的内容可能被重写
怎么快速定位是哪一层出了问题
别一上来就删 go.sum，先用两条命令缩小范围：
- 运行
go mod download -json github.com/xxx/yyy@v1.2.3，看输出里的Version和Sum字段是否与go.sum中该行一致 - 临时设
GOPROXY=direct再执行go mod verify，如果通过，说明是代理污染；如果仍失败，大概率是上游篡改 tag
注意：多 module 项目中，每个子模块都要单独验证，不能只查主模块的 go.sum。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
replace 指令 + checksum mismatch 是高危组合
本地开发用 replace github.com/xxx/yyy => ../yyy 很方便，但 go mod tidy 仍会去校验远程版本的哈希——如果那个远程版本已被覆盖，就会在校验阶段报错，哪怕你根本没用到它。
- CI 构建前必须删掉所有
replace，否则构建环境找不到../yyy路径，直接失败 - 若必须保留本地替换，应在
go.mod里加注释说明，并配合GOFLAGS="-mod=readonly"提前暴露问题 - 更稳妥的做法：用 commit hash 替代 tag，比如
go get github.com/xxx/yyy@abcd123，hash 不可篡改
CI 构建时校验失败的硬性检查点
Docker 构建或 CI 流水线里出错，往往是因为环境变量和本地开发不一致：
- 确认
GO111MODULE=on，不是auto（尤其在非 GOPATH 目录下） - 检查
GOPROXY是否包含,direct回退项，例如GOPROXY=https://goproxy.cn,https://proxy.golang.org,direct - 确保
GOPRIVATE已设（如GOPRIVATE=git.company.com/*），否则私有模块会被 proxy 拦截 - 不要在 Dockerfile 里写
RUN go clean -modcache—— 它清不干净 multi-stage 构建中的缓存，应改用go mod download -x查看真实下载路径再针对性清理
最易被忽略的是：多个子模块各自维护 go.sum，但 CI 只跑主模块的 go mod tidy，导致子模块依赖未更新、哈希记录陈旧。必须在构建前逐个进入子目录执行 go mod tidy。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
