go mod download失败或极慢的根本原因是默认代理proxy.golang.org在国内解析不稳定且被限流，go 1.13+强制启用代理模式但首代理不可达时不会自动fallback，需设goproxy=https://goproxy.cn,direct并配goprivate处理私有模块。
为什么 go mod download 会失败或极慢
国内直接运行 go mod download 时，常遇到超时、连接重置或 403 错误，根本原因是 Go 默认从 proxy.golang.org 拉取模块，该域名在国内解析不稳定，且部分 CDN 节点被限流。更关键的是，Go 1.13+ 强制启用代理模式（GOPROXY 默认为 https://proxy.golang.org,direct），一旦首代理不可达，不会自动 fallback 到 direct，而是报错退出。
设置本地代理：用 goproxy.io 或 goproxy.cn 替代官方源
最稳妥的本地代理方案是改用国内镜像服务，它们兼容 Go proxy 协议，无需自建服务，只需配置环境变量：
- 临时生效（当前终端）：
export GOPROXY=https://goproxy.cn,direct
- 永久生效（写入
~/.bashrc或~/.zshrc）：echo "export GOPROXY=https://goproxy.cn,direct" >> ~/.zshrc && source ~/.zshrc
- Windows PowerShell：
[Environment]::SetEnvironmentVariable("GOPROXY", "https://goproxy.cn,direct", "User")
注意：direct 必须保留，它作为兜底策略，确保私有模块（如公司内网 GitLab 地址）仍能直连；goproxy.cn 已稳定运营多年，比 goproxy.io 更少出现证书或重定向问题。
绕过代理下载私有模块：用 GONOPROXY 和 GOPRIVATE
若项目依赖公司内部 Git 仓库（如 git.example.com/internal/lib），默认会被代理拦截并返回 404。必须显式声明哪些模块不走代理：
- 设置
GOPRIVATE（推荐，Go 1.13+ 官方支持）：export GOPRIVATE=git.example.com/internal/*
- 等价写法（兼容旧版）：
export GONOPROXY=git.example.com/internal/*
- 支持通配符和多域名，用逗号分隔：
export GOPRIVATE="git.example.com/*,github.com/my-org/*"
否则会出现类似错误：go: git.example.com/internal/lib@v0.1.0: reading https://goproxy.cn/git.example.com/internal/lib/@v/v0.1.0.mod: 404 Not Found。
验证代理是否生效及调试技巧
执行 go env GOPROXY 确认值已更新；再运行 go mod download -x（加 -x 输出详细请求日志），观察实际访问的 URL 是否已变成 https://goproxy.cn/...。常见陷阱包括：
- IDE（如 Goland）未继承 shell 环境变量，需在 IDE 设置里单独配置
GOPROXY - 某些 CI 环境（如 GitHub Actions）需在
env:下显式声明，不能只靠run:命令 export -
go clean -modcache后首次下载仍慢——这是正常现象，代理缓存尚未建立，第二次起才会明显加速
代理本身不解决所有问题：如果模块引用了被墙的 replace 目标（比如指向某个 GitHub raw URL），那依然会卡住，得配合 go mod edit -replace 重定向到可访问地址。
