如何配置Golang模块代理_Golang依赖加速方案

必须显式设置GOPROXY环境变量，推荐export GOPROXY=https://goproxy.cn,direct，因其同步及时、sum校验完整且支持私有模块fallback到direct。

为什么 go mod download 总是卡在 proxy.golang.org

因为国内直连 proxy.golang.org 和 sum.golang.org 不稳定，常出现超时、403 或校验失败。Go 默认不走系统代理，且 GO111MODULE=on 后所有依赖都强制走模块代理，不配置就会反复失败。

• 不是网络问题，是 Go 模块协议本身要求校验 sum 文件，而 sum.golang.org 在国内不可靠
• GOPROXY 是唯一可控入口，必须显式设置，不能依赖环境变量自动继承
• 多个代理可串联，用逗号分隔，Go 会按顺序尝试，直到成功或全部失败

推荐的 GOPROXY 配置值及取舍

优先使用带校验兜底的组合，避免因代理自身缺失 sum 数据导致构建中断：

export GOPROXY=https://goproxy.cn,direct

这是目前最稳的配置 —— goproxy.cn 同步及时、sum 校验完整、支持私有模块 fallback 到 direct。其他常见选项对比：

• https://mirrors.aliyun.com/goproxy/：同步延迟略高，偶发 404，但域名更熟悉
• https://goproxy.io：已停止维护，不建议新项目使用
• https://proxy.golang.org：仅作兜底（如写成 https://goproxy.cn,https://proxy.golang.org），但需确保能连上 sum.golang.org，否则会报 checksum mismatch

如何验证代理是否生效

别只看 go env GOPROXY，要实际触发一次模块下载并观察行为：

• 删掉本地缓存：go clean -modcache
• 运行：go mod download github.com/spf13/cobra@v1.8.0
• 如果输出中出现 Fetching https://goproxy.cn/github.com/spf13/cobra/@v/v1.8.0.info，说明代理已生效
• 若仍看到 Fetching https://proxy.golang.org/...，检查是否被 shell 配置文件（如 ~/.zshrc）里的旧 export 覆盖，或 IDE 终端未重载环境变量

私有模块和 replace 场景下要注意什么

设置了 GOPROXY 后，replace 仍优先于代理，

但私有仓库（如 GitHub 私库、GitLab）默认会被代理拒绝，必须显式排除：

export GOPROXY=https://goproxy.cn,direct
export GONOPROXY=git.internal.company.com,github.com/my-org/private-repo

GONOPROXY 支持通配符（如 github.com/my-org/*），但注意：

• 它只控制「是否走代理」，不影响 go mod vendor 或 go build 的路径解析
• 如果私有模块用了 git+ssh 协议（如 git@github.com:org/repo.git），需确保 git 命令本身能访问（比如 SSH key 已配置）
• GONOSUMDB 要与 GONOPROXY 对齐，否则可能因 sum 校验失败退出：export GONOSUMDB=git.internal.company.com

有些团队把 GOPROXY 写进 go.work 或 go.mod，这是无效的 —— Go 模块代理纯属客户端环境行为，只认环境变量。