Go模块下载失败的解决方法是配置GOPROXY代理（如https://goproxy.cn,direct）并结合重试机制；需设置GOSUMDB和GOPRIVATE，必要时清理缓存或查看详细日志。
Go 模块下载失败很常见，尤其在国内网络环境下。核心解决思路是：配置代理加速下载 + 设置重试避免偶发失败。下面分两部分说明怎么做，不绕弯、可直接用。
配置 GOPROXY 代理（推荐使用国内镜像）
Go 1.13+ 默认启用模块模式，GOPROXY 环境变量控制模块下载源。设为国内镜像能大幅降低超时和 404 概率。
- 临时设置（当前终端生效）：
export GOPROXY=https://goproxy.cn,direct - 永久设置（写入 shell 配置）：
echo "export GOPROXY=https://goproxy.cn,direct" >> ~/.zshrc && source ~/.zshrc - 注意：末尾的 ,direct 表示对私有仓库（如公司内网 Git）跳过代理，直连拉取
- 备选镜像（按稳定性排序）：
• https://goproxy.cn（推荐，维护活跃）
• https://goproxy.io（已归档，不建议新项目）
• https://mirrors.aliyun.com/goproxy/（阿里云，需确认是否支持完整语义）
启用 Go 的自动重试机制
Go 本身不提供“重试次数”配置，但可通过组合环境变量和命令行为失败场景增加容错：
- 设置超时时间，避免卡死：
export GOSUMDB=off（跳过校验，适合调试；生产建议用 sum.golang.org 或国内镜像） - 手动重试命令（适合 CI/CD 或脚本）：
go mod download -x 2>&1 | grep -i "timeout\|denied\|no such" && go mod download
——先执行一次，检测关键错误关键词，命中则再跑一遍 - 更稳妥的做法：在 CI 脚本中用循环重试（例如最多 3 次）：
for i in {1..3}; do go mod download && break || sleep 2; done
排查与兜底方案
如果代理+重试仍失败，可能是模块地址异常或本地缓存损坏：
立即学习“go语言免费学习笔记（深入）”；
- 查看详细日志定位问题：
go mod download -x（显示每一步 fetch 过程） - 清理可疑缓存：
go clean -modcache（清空整个 module 缓存，下次重新下载） - 检查 go.sum 是否冲突：
go mod verify 失败时，可尝试 go mod tidy -v 重建依赖树 - 私有模块无法走代理？确认 GOPRIVATE 已设置：
export GOPRIVATE=git.example.com/myrepo,github.com/myorg/private
代理和重试不是万能，但覆盖了 95% 的下载失败场景。关键是把 GOPROXY 设对、GOSUMDB 和 GOPRIVATE 配好，再辅以简单重试逻辑，基本就稳了。
