go模块依赖下载失败或版本错误，90%源于代理配置、replace规则或go.sum校验问题；需确认go111module=on，设goproxy=https://goproxy.cn,direct，私有库配gonoproxy，replace路径须完全匹配，checksum mismatch时优先go clean -modcache而非删go.sum。
Go模块依赖下载失败或版本不对，90%是代理、replace规则或go.sum校验三者之一出问题，不是代码写错了。
go mod download 总卡住或报错
常见现象是命令卡在某个模块、提示 Get "https://proxy.golang.org/..." 超时，或直接报 no matching versions for query "latest"。
- 先确认
GO111MODULE=on（不是auto），否则 go 命令会退化回 GOPATH 模式，忽略go.mod - 检查
GOPROXY是否生效：go env GOPROXY，国内推荐设为https://goproxy.cn,direct；direct是兜底项，确保私有库能直连 - 若依赖来自 GitLab 或公司内网仓库，需同时配置
GONOPROXY，例如：go env -w GONOPROXY="git.internal.company.com/*"，否则代理会拦截导致 404 - 个别模块（如含特殊字符或未打 tag 的 repo）不支持
latest查询，必须显式指定版本：go get github.com/user/repo@v0.3.1
replace 规则不生效的典型原因
replace 写进 go.mod 后，go build 仍用远程版本，说明规则没被加载或被覆盖。
-
replace只对当前模块及其直接/间接依赖生效，不能跨go.work工作区影响其他模块 - 路径必须完全匹配：比如依赖是
github.com/foo/bar，replace的左边就不能写成foo/bar或带v2后缀 - 本地路径替换必须是绝对路径或相对于当前
go.mod的相对路径，且目标目录下必须有合法的go.mod文件 - 如果同时存在多个
replace，后声明的会覆盖前一个；exclude与replace共存时，exclude优先级更高
go.sum 校验失败导致下载中断
错误信息通常是 verifying github.com/xxx@v1.2.3: checksum mismatch，本质是本地缓存的模块内容和 go.sum 记录的哈希不一致。
- 不要手动删
go.sum—— 它不是日志文件，而是安全凭证。删了会导致后续构建无法验证依赖完整性 - 先运行
go mod download -dirty查看哪些模块哈希异常；再用go mod verify确认是否所有模块都通过校验 - 若确定是网络中间件篡改（如公司代理重写 git blob），可临时禁用校验：
go env -w GOSUMDB=off，但仅限离线调试，上线前必须恢复 - 私有模块若无签名，建议用
GOSUMDB=sum.golang.org+local配合自建 checksum server，而非彻底关掉
依赖升级后行为异常，其实是间接依赖没清理干净
执行 go get -u 或 go get package@v2.0.0 后，程序 panic 或类型不匹配，大概率是旧版间接依赖还在缓存里没被剔除。
-
go mod tidy不等于“自动更新所有依赖”——它只增删go.mod中显式声明的依赖，不会主动降级或清理间接依赖的旧版本 - 运行
go mod graph | grep old-package-name查看谁还在引用旧版；再用go mod why old-package-name定位源头 - 强制清理全部间接依赖缓存：
go clean -modcache，然后重新go mod tidy，这步在 CI 环境尤其关键 - 注意
go get -u默认只升到最新 minor 版，要升到 v2+ 大版本必须显式加@v2.0.0，否则会被语义化版本规则拦住
真正麻烦的从来不是怎么写 replace 或怎么设 proxy，而是不同模块间 go.sum 哈希冲突、GONOPROXY 路径匹配不全、以及 go mod tidy 对间接依赖的“选择性失明”。这些点不手动验证一遍，光靠命令行提示很难定位。
