Go模块下载失败主因是GOPROXY和GOPRIVATE配置不当、网络或私有路由错误；应设GOPROXY为goproxy.cn等可用代理并配GOPRIVATE跳过私有模块代理，再清理缓存或关GOSUMDB调试。
Go 模块下载失败，90% 以上是 GOPROXY 配置、网络连通性或私有模块路由错误导致的，不是代码或 Go 版本问题。
确认并强制切换到可用代理
国内用户默认的 https://proxy.golang.org 基本不可用，且 Go 1.13+ 启用模块模式后会严格走代理，不手动设就卡死或超时。
- 立即执行（推荐七牛源，稳定且支持 direct fallback）：
go env -w GOPROXY=https://goproxy.cn,direct
- 如需多级兜底（例如清华源 + 七牛 + 直连），可写成：
go env -w GOPROXY="https://mirrors.tuna.tsinghua.edu.cn/go/modules/,https://goproxy.cn,direct"
- 验证是否生效：
go env GOPROXY应输出你刚设置的值，不是空或默认地址 - ⚠️ 常见坑：IDE（如 Goland/VSCode）内置终端可能读取自己的环境变量配置，和系统 shell 不一致 —— 务必在 IDE 终端里也运行一遍
go env -w GOPROXY=...，或检查 IDE 的 Go 设置页是否覆盖了GOPROXY
私有模块 403 或 “module lookup failed”？立刻配 GOPRIVATE
一旦 GOPROXY 设为公共镜像，所有模块（包括 git.company.com 或 github.com/my-org/private-repo）都会被转发过去，结果就是 403 或无法解析 —— 这不是权限问题，是路由错位。
- 把私有域名加进
GOPRIVATE，让 Go 自动跳过代理直连：go env -w GOPRIVATE="git.company.com,github.com/my-org/*"
- 支持通配符（
*），但不支持正则；多个用英文逗号分隔，**不能有空格** - 若用 SSH 克隆私有库，还需确保
git能正常访问（ssh -T git@git.company.com测试）；若用 HTTPS，则需提前配置 Git 凭据或设置GIT_TERMINAL_PROMPT=0避免卡住
下载卡住、校验失败或 zip: not a valid zip file
这类报错往往不是网络问题，而是缓存污染或校验数据库（GOSUMDB）不可达导致的“假失败”。
- 先清理本地模块缓存：
go clean -modcache
（注意：这会清空所有已下载模块，后续首次go mod download会稍慢） - 若报
checksum mismatch，大概率是sum.golang.org访问失败 —— 可临时关闭校验验证是否是此原因：go env -w GOSUMDB=off
（仅调试用，切勿提交或长期开启） - 遇到
zip: not a valid zip file，说明某模块缓存损坏，直接删掉对应路径即可（如报错含github.com/some/pkg，就删$GOPATH/pkg/mod/cache/download/github.com/some/pkg下的整个目录） - 加
-v看详细过程：go mod download -v，能清晰看到每个模块从哪个 URL 拉取、HTTP 状态码、重定向链路，比盲猜高效得多
临时绕过代理快速验证问题根因
当不确定是代理挂了、网络断了，还是配置错了，最有效的方式是“隔离变量”测试。
- 本次命令不走代理：
GOPROXY=direct go mod download
- 本次只换代理不改全局：
GOPROXY=https://goproxy.cn go mod download
- 配合
curl测试代理连通性：curl -I https://goproxy.cn（应返回 200 或 302）；若超时，说明代理本身不可达，不是 Go 配置问题 - 如果
GOPROXY=direct成功，但设了代理就失败，基本可锁定为代理地址错误、GOPRIVATE漏配、或代理服务临时异常
真正麻烦的不是某个命令失败，而是 GOPROXY 和 GOPRIVATE 配对关系没理清 —— 它们必须协同工作，缺一不可。很多人反复换代理却忽略后者，结果永远在 403 和 timeout 之间横跳。
