go模块下载失败主因是代理链配置不当，需设goproxy为多级fallback（如https://mirrors.tuna.tsinghua.edu.cn/go/modules/,https://goproxy.cn,direct）并配goprivate跳过私有模块代理，再清理缓存或关gosumdb调试。
第三方 Go 代理（如 proxy.golang.org、goproxy.io）宕机时，go mod download 会卡在 fetch 阶段或报 dial tcp: i/o timeout，但问题不在你本地代码或网络——是代理链断了。解决方案不是等它恢复，而是让 Go 工具链自动 fallback 到可用节点。
为什么单个代理宕机会导致整个下载失败
Go 默认的 GOPROXY 值是 https://proxy.golang.org,direct，注意中间是英文逗号，不是空格。但很多人误设为 https://goproxy.cn（漏掉 ,direct），结果一旦该镜像临时不可用，Go 就不会尝试后续选项，直接失败。更隐蔽的问题是：某些企业内网 DNS 会劫持或缓存失败响应，导致即使代理恢复，本地仍持续超时数分钟。
-
GOPROXY是严格顺序尝试的，遇到第一个可连通且返回 HTTP 2xx 的地址就停；404、503、timeout 都算“不可用”，继续下一个 -
direct不是“不走代理”，而是让 Go 直连模块源仓库（如 GitHub、GitLab），但它要求模块服务器支持/@v/xxx.info等 Go modules 协议端点——私有 Git 服务往往不支持，所以必须配合GOPRIVATE - 如果用了
GOSUMDB=off，校验跳过，但go mod download仍需成功拉取源码；如果用了GOSUMDB=sum.golang.org+replace=...，替换后的校验服务也得在线
配置多级 fallback 代理并验证是否生效
把至少两个国内稳定镜像 + direct 组成 fallback 链，避免单点故障。清华源和七牛云目前（2026 年中）同步延迟最低、SLA 最稳：
go env -w GOPROXY="https://mirrors.tuna.tsinghua.edu.cn/go/modules/,https://goproxy.cn,direct"
注意：, 是分隔符，/ 结尾对清华源是必须的（否则 404），而 goproxy.cn 不需要结尾斜杠。设完后必须验证：
- 运行
go env GOPROXY，输出应与上面完全一致（含空格、斜杠、逗号） - 执行
go mod download -x github.com/gin-gonic/gin@v1.9.1，观察日志里是否依次出现GET https://mirrors.tuna...→ 超时 →GET https://goproxy.cn...→ 成功 - 别只信
go list -m all是否成功——它可能从本地缓存读取，要真触发网络请求才有效
私有模块混用时 fallback 容易失效的坑
如果你的 go.mod 里同时引用了公开模块（如 github.com/sirupsen/logrus）和私有模块（如 git.internal.company.com/my/lib），只配 GOPROXY 不够——Go 会把私有域名也发给代理，结果返回 403 或 404，然后整条依赖链中断，哪怕 public 模块的代理是好的。
- 必须设置
GOPRIVATE（不是GONOPROXY，后者已弃用）：go env -w GOPRIVATE="git.internal.company.com,github.com/my-org/*"
-
GOPRIVATE值必须精确匹配模块路径前缀，不支持正则，逗号分隔无空格 - 若私有库走 SSH（
git@git.internal...），directfallback 才能生效；若走 HTTPS 且需 Basic Auth，确保~/.netrc已配置凭据，否则direct也会 401
CI/CD 中代理失效的静默陷阱
Docker 构建或 GitHub Actions 里，go env -w 写入的环境变量常被忽略——因为 Go 工具链启动新进程时，不会自动继承 shell 的 export 设置，尤其在 alpine 镜像中默认没读 /etc/profile。
- 在
Dockerfile中，不要只写go env -w GOPROXY=...，要显式导出：ENV GOPROXY=https://goproxy.cn,direct
- GitHub Actions 中，用
env:块注入，而非run:里执行go env -w（后者只影响当前 step） - 关键动作加
-v：go mod download -v日志里必须看到Fetching ... from https://goproxy.cn，否则代理根本没走
最麻烦的不是代理挂了，而是你改了配置却没意识到 Go 某些命令（比如 go install）会绕过 GOPROXY 直连，或者 IDE 缓存了旧环境变量——每次换代理后，重启终端和编辑器比反复检查配置更省时间。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
