GolangGOPROXY设置及国内镜像推荐

正确配置 Go 模块代理需三步协同：必须将 GOPROXY 设为 `https://goproxy.cn,direct`（缺一不可，` ,direct` 是私有模块直连的关键fallback），同时强制启用 `GO111MODULE=on` 以确保模块模式生效，并针对公司内网或私有仓库配置 `GOPRIVATE` 排除代理和校验；若忽略任一环节——如漏写 `,direct`、未开启模块模式、未设置 GOPRIVATE，或误配系统代理、URL末尾多斜杠等细节，都会导致私有模块下载失败、依赖拉取缓慢甚至完全卡死，真正生效的验证必须通过实际 `go get` 行为观察网络请求路径，而非仅检查环境变量输出。

怎么设置 GOPROXY 才真正生效

只写 GOPROXY=https://goproxy.cn 是常见错误——漏掉 ,direct 会导致私有模块（如公司内网 Git）完全无法下载，报错类似 module not found 或卡在 Fetching。Go 要求代理地址后必须明确 fallback 策略，,direct 就是告诉它：“镜像里没有的，直接连源仓库”。

• 推荐命令（永久生效，macOS/Linux zsh）：echo "export GOPROXY=https://goproxy.cn,direct" >> ~/.zshrc && source ~/.zshrc
• Windows PowerShell 用户用：[System.Environment]::SetEnvironmentVariable('GOPROXY', 'https://goproxy.cn,direct', 'User')
• 设置后务必验证：go env GOPROXY 输出应为 https://goproxy.cn,direct，不是空、不是 https://proxy.golang.org,direct
• 如果输出不对，检查是否拼错变量名（GOPROXY 区分大小写）、是否漏了 source 或未重启终端

为什么一定要配 GO111MODULE=on

即使 GOPROXY 设置正确，若 GO111MODULE 被关掉（值为 off），Go 会退回到 GOPATH 模式，完全忽略 GOPROXY 和 go.mod，所有 go get 都直连 GitHub，速度慢且易失败。

• 强制启用模块模式：go env -w GO111MODULE=on
• 该设置与 GOPROXY 是绑定生效的前提，不是可选项
• 老项目迁移时容易残留 GO111MODULE=auto，在无 go.mod 的目录下仍可能退化，建议统一设为 on

私有模块下载失败？检查 GOPRIVATE 是否配置

当项目引用 git.company.com/internal/pkg 或 github.com/myorg/private 这类非公开模块时，仅靠 ,direct 不够——Go 默认仍会尝试向代理发起请求，而国内镜像不缓存私有路径，结果 404 或超时。

• 明确排除代理：go env -w GOPRIVATE="git.company.com,github.com/myorg"
• GOPRIVATE 支持通配符，但注意它匹配的是模块路径前缀，不是域名；github.com/myorg/* 写法无效，应写 github.com/myorg
• 多个域名用逗号分隔，不能有空格：git.company.com,gitlab.internal,bitbucket.org/ourteam
• 配置后，这些模块将跳过代理和校验（GOSUMDB 也会自动绕过），确保直连可用

测试代理是否真起作用的最简方法

别只看 go env GOPROXY 输出，要观察实际行为。最可靠的方式是触发一次真实下载，并确认请求没发往 proxy.golang.org。

• 新建空目录，执行：go mod init example.com/test && go get github.com/sirupsen/logrus@v1.9.0
• 成功时应秒级完成，并在输出中看到类似 verifying github.com/sirupsen/logrus@v1.9.0，而非长时间卡在 Fetching
• 若仍慢或报错，加 -v 查日志：go get -v github.com/sirupsen/logrus，看第一行是否显示 Fetching https://goproxy.cn/github.com/sirupsen/logrus/@v/v1.9.0.info
• 临时覆盖测试（不影响全局）：GOPROXY=https://mirrors.aliyun.com/goproxy/ go mod download

最容易被忽略的点：很多人设了 GOPROXY 却没关掉本地 HTTP/HTTPS 代理（比如系统级的 Shadowsocks 或 Charles），导致 Go 请求被二次拦截；还有人把 GOPROXY 值末尾多打了个斜杠（https://goproxy.cn/），Go 会当作非法 URL 直接忽略，退回到默认代理。

今天关于《GolangGOPROXY设置及国内镜像推荐》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！