Go 拉取私有模块时 GOPROXY 和 GOPRIVATE 怎么配

Go 拉取私有模块时，先别把所有问题都归到 GOPROXY。如果私有模块要直接从 Git 仓库下载，通常保留 GOPROXY=https://proxy.golang.org,direct，再设置 GOPRIVATE=git.corp.example.com；如果公司代理本身托管私有模块，则应让请求留在私有代理，并单独设置 GONOSUMDB。前者控制“从哪里下载”，后者解决“哪些模块不走公共代理和公共校验库”。

最稳妥的判断顺序是：先决定私有模块应该到私有代理还是版本库，再决定它是否需要绕开公共 sumdb；不要用 GOSUMDB=off 代替精确的私有模块匹配。

一、先分清 GOPROXY 和 GOPRIVATE 各自管什么

GOPROXY 是模块下载来源列表，默认通常是 https://proxy.golang.org,direct。direct 表示回到模块对应的版本库。GOPRIVATE 是私有模块路径前缀的匹配规则，并且默认作为 GONOPROXY 与 GONOSUMDB 的值：匹配到的模块既不从公共代理取，也不向公共 checksum database 查询。

所以一个组织域名为 git.corp.example.com、私有模块路径为 git.corp.example.com/pay/order 时，直连版本库的最小配置可以写成：

# 私有模块直连 VCS；公共模块仍可使用默认代理
go env -w GOPROXY=https://proxy.golang.org,direct
# 用模块路径前缀匹配组织内的私有模块
go env -w GOPRIVATE=git.corp.example.com

二、按部署形态选择配置组合

如果没有私有模块代理，使用上面的直连方案，并确保 Git 已配置非交互式凭据。若公司代理托管私有模块，则不要让 GOPRIVATE 的默认 GONOPROXY 把请求直接导向 Git；可以让私有代理优先、公共代理负责公开依赖：

# 私有代理托管内网模块，公开模块可继续从公共代理获取
go env -w GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org,direct
# 私有模块不向公共 checksum database 查询
go env -w GONOSUMDB=git.corp.example.com
# 若机器已有全局 GOPRIVATE，显式避免它把私有代理绕开
go env -w GONOPROXY=none

这里的 GONOSUMDB 只处理校验数据库访问，不等于关闭模块完整性校验；私有代理仍应提供可信的模块内容与访问控制。若私有代理只服务私有模块，也要确认它对不存在的模块返回 404 或 410，否则 Go 不会按预期继续请求后面的来源。

三、用回退规则定位代理错误

GOPROXY=a,b,direct 中的逗号表示：当前代理返回 404 或 410，Go 才继续下一个来源；403、认证失败或服务端错误通常会终止当前查找。使用竖线写成 a|b|direct，才会对任意 HTTP 错误继续尝试，适合明确知道代理故障也不应阻断后备来源的场景，但会掩盖权限或策略问题。

因此，私有代理返回 403 时不要先改成竖线。先查代理是否要求登录、模块路径是否匹配、CI 是否有读取权限；否则一旦放宽回退，私有模块路径可能被带到不应访问的后续来源。这个判断也能解释“本地能拉、CI 拉不到”：两边往往不是 Go 版本差异，而是代理凭据和错误码不同。

四、出现校验失败时按顺序排查

先把实际生效值打印出来，确认没有被 shell、镜像构建参数或 CI 全局配置覆盖：

# 先看 Go 实际使用的代理、私有匹配和校验策略
go env GOPROXY GOPRIVATE GONOPROXY GONOSUMDB GOSUMDB
# 只验证一个私有模块的下载路径，不把整棵依赖树混在一起
go mod download -x git.corp.example.com/pay/order@v0.4.0

若日志先请求公共代理，通常是 GOPRIVATE 没匹配到完整模块前缀；若直接进入 Git 后提示认证，检查 Git 的凭据、SSH 重写规则和 CI 的只读权限；若错误指向 sum.golang.org，再检查 GONOSUMDB 是否覆盖该模块。公开依赖仍应保留校验，不建议为了一个私有路径全局设置 GOSUMDB=off。

相关问题

GOPRIVATE 应该写仓库地址还是模块路径？

写模块路径的前缀，不是带协议的 Git URL。优先写能覆盖组织模块的最短明确前缀，例如 git.corp.example.com。

设置了 GOPRIVATE 后为什么内网代理不再收到请求？

因为它默认也充当 GONOPROXY。若私有代理负责托管这些模块，应改为精确的 GONOPROXY 规则或使用 GONOPROXY=none，同时保留 GONOSUMDB 的私有匹配。

GOSUMDB=off 能解决私有模块校验错误吗？

它会对所有未在 go.sum 中的模块放弃公共校验，影响范围过大。只对私有模块设置 GONOSUMDB 更容易审计和回滚。

本文依据 Go Modules Reference 与 Go 官方依赖管理指南 中的代理、私有模块和 checksum database 规则整理。配置变更后，保留一条最小的 go mod download -x 日志，后续排障会比只看最终错误更快。