根本原因是环境配置、缓存污染或网络策略不一致；应先执行go clean -modcache清理缓存，再用go mod tidy -v定位失败模块，遇checksum mismatch优先检查goproxy和goprivate配置，必要时临时设gosumdb=off验证，避免手动删go.sum。
Go模块依赖下载失败或校验不匹配，根本原因通常不是代码写错了，而是环境配置、缓存污染或网络策略没对齐。直接上有效命令，不绕弯。
go mod tidy 无输出但依赖没下载？先清缓存再重试
这不是命令失效，而是模块缓存（$GOPATH/pkg/mod）里残留了旧路径映射或损坏的包。尤其在改过 go.mod 的 module 声明、重命名项目目录、或切换分支后极易发生。
- 执行
go clean -modcache—— 这是最干净的清理方式，比手动删pkg/mod更安全 - 确认
go.mod中的模块路径与当前目录结构一致（比如module github.com/your-org/project要对应实际路径） - 再跑
go mod tidy -v，加-v能看到每一步拉取动作，卡在哪一包就定位到哪
checksum mismatch 错误：别急着删 go.sum
报错类似 verifying github.com/xxx@v1.2.3: checksum mismatch，说明本地下载的包和 go.sum 记录的哈希对不上。常见于私有仓库更新、镜像源缓存不一致、或有人手动改过依赖文件。
- 优先运行
go mod download -v，看具体是哪个模块出问题；如果它卡在某个私有域名，大概率是GOPRIVATE没配全 - 临时用
GOSUMDB=off go mod tidy绕过校验（仅限开发环境），验证是否真为校验机制阻塞 - 若确认是镜像源问题（如清华源同步延迟），可换代理：
go env -w GOPROXY=https://goproxy.cn,direct - 不建议直接删
go.sum—— 它不是“缓存”，而是安全凭证；应让go mod tidy自动重生成校验行
GOPROXY 配错导致 timeout 或 403？三步现场诊断
国内最常踩的坑：代理地址拼错、私有域名没加进 GOPRIVATE、或 fallback 顺序不合理。
- 查当前配置：
go env GOPROXY GOPRIVATE—— 确保GOPRIVATE包含所有私有域名（如git.internal.company,github.com/my-team/*），逗号分隔无空格 - 测试代理连通性：
curl -I https://goproxy.cn/github.com/golang/net/@v/v0.28.0.info（替换任意已知公开模块） - 临时切 direct 模式验证：
GOPROXY=direct go list -m all—— 如果能成功，说明问题出在代理链，而非网络本身
真正麻烦的不是命令记不住，而是同一个错误背后可能有四五种成因：缓存脏、代理挂、私有域漏、go.sum 被编辑过、甚至 Git 标签被 retract。每次遇到先跑 go mod download -v，盯着最后一行失败的 URL，比猜快得多。
