Go GOPROXY 回退策略与私有模块认证配置

公共模块代理、公司私有代理和内部 Git 仓库混在一起时，推荐把“去哪里找模块”和“怎么证明模块没被篡改”分开配置：用 GOPROXY 决定下载路径，用 GOPRIVATE 标记私有前缀，再让代理或 Git 自己完成认证。真正容易踩坑的是回退分隔符：逗号只对 404/410 回退，竖线会把超时等错误也交给下一个来源。

官方资料：https://go.dev/ref/mod

先把三类下载路径分清

GOPROXY 是来源列表，direct 表示直接访问版本控制仓库，off 则完全禁止网络下载。比如内网代理只负责私有模块、公共模块交给官方代理，可以这样写：

# 先查内网代理；明确不存在时再查公共代理，最后才直连仓库
go env -w GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org,direct

# 私有模块前缀不送往公共代理和公共 checksum 数据库
go env -w GOPRIVATE=corp.example.com

这里的逗号不是普通的“继续尝试”。内网代理返回 403、认证失败或网络错误时，Go 会把它当作终止错误，不会静默绕到公共来源；这能避免策略错误被掩盖，也能减少私有模块路径外泄。

回退策略要按错误边界选择

生产环境更建议先用逗号，先确认代理返回码设计正确。只有在明确接受“代理短暂不可用时绕过它”的场景，才使用竖线；否则一次超时就可能把请求带到不希望访问的下一个来源。

私有模块的隐私与认证分别配置

GOPRIVATE 解决的是路径隐私和校验范围，不等于已经登录。若内网代理服务私有模块，可保留 GOPROXY，并只把私有前缀写入 GONOSUMDB；若没有私有代理，则让匹配的模块走 direct，并给 Git 配置非交互凭据。

# 私有代理统一承载公共与私有模块时，不要额外设置 GONOPROXY
go env -w GOPROXY=https://proxy.corp.example.com
go env -w GONOSUMDB=corp.example.com

# 没有私有代理时，GOPRIVATE 会使匹配模块绕过公共代理和公共校验库
go env -w GOPRIVATE=corp.example.com

代理认证可以使用当前用户的 ~/.netrc；较新的 Go 还支持 GOAUTH，适合按 HTTPS 路径提供更细粒度的请求头。直接拉取私有仓库时，Git 的 credential helper、SSH 配置或 URL 重写才是认证层，Go 本身不会替你保存 Git 密码。CI 中要关闭交互式输入，并通过密钥管理系统注入凭据。

# .netrc 只示意代理主机，文件权限应限制为当前用户可读写
machine proxy.corp.example.com
login build-bot
password ${PROXY_PASSWORD}

# 检查 Go 实际读取的关键配置；不要把密码打印到日志
go env GOPROXY GOPRIVATE GONOPROXY GONOSUMDB GOAUTH

用最小命令定位失败层

先看配置，再只下载一个明确的私有模块版本。错误信息通常能区分代理返回码、checksum 请求和 Git 权限；不要一上来删除整个模块缓存。

# 只读取配置并显示模块下载详情，避免把凭据写入命令行
go env GOPROXY GOPRIVATE GONOPROXY GONOSUMDB
GONOSUMDB=corp.example.com go mod download -x corp.example.com/team/lib@v1.2.3

# 检查仓库工具是否会等待交互输入；CI 中应由凭据 helper 直接回答
GIT_TERMINAL_PROMPT=0 git ls-remote https://git.corp.example.com/team/lib.git

排查时可按这张清单收敛范围：

• 报 404/410：确认模块是否真的存在于当前代理，再看下一来源是否符合预期。
• 报 401/403：先修代理或 Git 凭据，不要用竖线掩盖权限错误。
• 报 checksum 错误：确认私有前缀是否匹配 GONOSUMDB，不要全局关闭 GOSUMDB。
• 报超时：判断是否允许跨代理故障转移，再决定是否把逗号改成竖线。

相关问题

GOPRIVATE 设置后还需要 GONOPROXY 吗

通常不需要。GOPRIVATE 默认作为 GONOPROXY 和 GONOSUMDB 的默认值；只有代理与校验服务需要不同边界时才拆开配置。

为什么代理超时后没有走 direct

如果列表使用逗号，超时属于终止错误；把分隔符改为竖线前，先确认绕过代理不会违反组织的出口、审计或依赖来源策略。

把 token 写进 GOPROXY URL 可以吗

技术上可以，但环境变量可能进入 shell 历史和日志。优先使用 .netrc、GOAUTH 或 Git credential helper。