Go模块下载失败怎么办_Go mod download常见问题处理_技术教程

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

一旦 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 避免卡住

这类报错往往不是网络问题，而是缓存污染或校验数据库（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，就删 $G OPATH/pkg/mod/cache/download/github.com/some/pkg 下的整个目录）
加 -v 看详细过程：go mod download -v，能清晰看到每个模块从哪个 URL 拉取、HTTP 状态码、重定向链路，比盲猜高效得多

当不确定是代理挂了、网络断了，还是配置错了，最有效的方式是“隔离变量”测试。

本次只换代理不改全局：

GOPROXY=https://goproxy.cn go mod download

配合 curl 测试代理连通性：curl -I https://goproxy.cn（应返回 200 或 302）；若超时，说明代理本身不可达，不是 Go 配置问题
如果 GOPROXY=direct 成功，但设了代理就失败，基本可锁定为代理地址错误、GOPRIVATE 漏配、或代理服务临时异常

真正麻烦的不是某个命令失败，而是 GOPROXY 和 GOPRIVATE 配对关系没理清 —— 它们必须协同工作，缺一不可。很多人反复换代理却忽略后者，结果永远在 403 和 timeout 之间横跳。