如何配置Golang模块下载代理_Golang GOPROXY设置说明

必须配置 GOPROXY，因 Go 1.13+ 默认启用模块且官方代理 proxy.golang.org 国内不可达，直连源站常被拦截；正确配置应为 https://goproxy.cn,direct，推荐用 go env -w 全局设置并配合 GOPRIVATE 处理私有仓库。

国内用 go get 或 go mod tidy 下载依赖失败、卡在 fetching dependencies，基本就是 GOPROXY 没配对——不是没设，而是设错了顺序、漏了回退机制，或混淆了生效范围。

为什么必须配 GOPROXY？

Go 1.13+ 默认启用模块（GO111MODULE=on），所有依赖都走模块协议下载。官方默认代理是 https://proxy.golang.org，但该域名在国内多数网络环境下无法解析或连接超时。不配代理时，Go 会尝试直连 GitHub、GitLab 等源站，而这些请求常被限速、重置或拦截，导致模块拉取失败或极慢。

• GOPROXY 不是“可选优化”，而是国内开发的必备前置项
• 仅设 https://goproxy.cn 不够：私有仓库（如公司内网 Git）、未被镜像的模块会直接报错，必须带 direct 回退
• off 和 direct 容易混用：off 是彻底禁用代理（危险），direct 是“此路不通就自己去源站拿”（安全）

三种配置方式，优先级和坑点全说清

配置方式按作用范围从小到大排列，但**推荐只用全局方式**，避免终端间行为不一致：

• 临时设置（当前终端有效）：

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

  关掉终端就失效，适合调试单次命令，比如：

  GOPROXY=https://goproxy.cn go get github.com/go-sql-driver/mysql@v1.7.0

• 用户级持久化（写入 shell 配置）：追加到 ~/.zshrc（macOS）或 ~/.bashrc（Linux），再执行 source ~/.zshrc。注意 Windows PowerShell 要用：

  $env:GOPROXY="https://goproxy.cn,direct"

  但该设置不会继承到 VS Code 的集成终端，除非手动 reload
• 全局配置（强烈推荐）：运行

  go env -w GOPROXY=https://goproxy.cn,direct

  它会把值写进 Go 自己的配置文件（路径类似 $HOME/go/env），对所有终端、IDE、CI 环境生效，且不受 shell 类型影响

验证是否真正生效？别只看 go env GOPROXY

go env GOPROXY 显示正确 ≠ 实际能用。常见假成功现象：

• 输出是 https://goproxy.cn,direct，但 go mod tidy 仍卡住 → 可能网络无法访问 goproxy.cn（试试浏览器打开 https://goproxy.cn/github.com/go-sql-driver/mysql/@v/v1.7.0.info）
• 报错 module github.com/xxx/yyy: reading https://goproxy.cn/...: 404 Not Found → 镜像暂未缓存该模块，此时应自动 fallback 到 direct；若没 fallback，说明配置里漏了 ,direct 或用了 off
• 私有模块（如 git.mycompany.com/internal/lib）下载失败 → 需额外设置 GOPRIVATE：

  go env -w GOPRIVATE=git.mycompany.com

  否则 Go 仍会先发请求到代理，再因 401/403 中断

VS Code 里还单独配 go.toolsEnvVars？没必要

很多人在 .vscode/settings.json 里写：

"go.toolsEnvVars": { "GOPROXY": "https://goproxy.cn" }

这是冗余操作。只要全局执行过 go env -w GOPROXY=...，VS Code 启动的 gopls、go 命令都会读取该值。重复配置反而容易冲突（比如 shell 终端用 goproxy.cn,direct，VS Code 里只写了 goproxy.cn，私有模块就挂了）。

真正要留意的是：VS Code 的集成终端启动时，可能不会自动加载你改过的 ~/.zshrc，所以务必用 go env -w 全局配置，而不是依赖 shell 初始化。