GOPRIVATE 配置私有模块下载与校验边界

如果 Go 项目依赖了企业内部模块，最小配置通常是把私有模块路径写进 GOPRIVATE。它告诉 go 命令：匹配这些路径的模块不应按公开模块处理，默认绕开公共模块代理和公共校验数据库。需要注意的是，GOPRIVATE 只解决“哪些路径属于私有”这一判断，不会替你创建代理、授予 Git 权限，也不会让所有模块都停止校验。

官方文档：https://go.dev/ref/mod#private-modules

把问题拆成三个边界就不容易配错：GOPRIVATE 负责路径分类，GONOPROXY/GOPROXY 负责下载来源，GONOSUMDB/GOSUMDB 负责校验来源；仓库登录则仍由 Git 或其他版本控制工具的凭据配置负责。

先把私有模块的三个边界分开

一次模块下载可能同时涉及模块代理、版本控制仓库和校验数据库。默认情况下，Go 会优先使用公共代理，并可能向公共校验数据库查询模块哈希。私有模块不应该把完整路径发往这些公共服务，因此要先声明私有路径。

用路径模式声明哪些模块是私有的

GOPRIVATE 的值是逗号分隔的 glob 模式，匹配模块路径前缀。企业模块常见的写法是组织域名或组织域名下的子域名；如果既有根域名模块，又有子域名模块，建议显式写出两种模式，避免读者把通配符覆盖范围想当然。

# 只把公司模块前缀标记为私有，不影响公开依赖的默认行为
go env -w GOPRIVATE=corp.example.com,*.corp.example.com

# 查看 Go 实际保存的值，确认没有把引号或空格写进模式
go env GOPRIVATE

这里的模式只描述模块路径，不是 Git 仓库密码，也不是代理地址。比如模块路径是 corp.example.com/payments/sdk，它会被上面的模式命中；公开的 github.com/org/public-lib 不会因为同一项目使用了 GOPRIVATE 就自动变成私有。

如果私有模块直接来自版本控制仓库，Go 仍然需要能够定位仓库并读取代码。模块路径没有携带仓库根提示时，Go 可能访问该域名的 ?go-get=1 入口来发现仓库地址；因此，内部域名解析、仓库元数据和 Git 凭据都属于另一个配置层。

直连仓库时，GOPRIVATE 只负责避开公开服务

不使用企业模块代理时，可以保留公共代理对公开依赖的默认回退，并用 GOPRIVATE 让私有依赖避开公共代理与公共校验数据库。适合把私有仓库作为唯一可信下载源、且团队已经配置好非交互式 Git 凭据的场景。

# 私有模块走版本控制仓库，公开模块仍可使用公共代理
go env -w GOPRIVATE=corp.example.com,*.corp.example.com
go env -w GOPROXY=https://proxy.golang.org,direct

# 只显示配置，不打印 Git 密码、访问令牌或完整凭据
go env GOPRIVATE GOPROXY GONOPROXY GONOSUMDB GOSUMDB

官方默认值中的 direct 是代理返回 404 或 410 时的回退路径；它不是“所有依赖都强制直连”。对于私有模块，GOPRIVATE 会让公共代理和公共校验数据库不参与该路径的默认处理，但仓库访问失败仍可能来自 SSH、HTTPS、证书、权限或内部 DNS。

另外，Go 调用 Git 时默认关闭交互式终端提示。如果 CI 里看到“无法读取私有模块”，不要先把 GOSUMDB=off 当作万能修复；先确认执行用户的 Git 凭据、仓库读权限和非交互登录链路。

使用私有代理时，要覆盖默认决策

如果企业代理已经缓存或提供私有模块，下载路径应由代理策略决定。此时最容易出现的误区是：只设置了 GOPRIVATE，却忘了它默认会让私有模块绕开代理。私有代理明确服务私有模块时，可以用 GONOPROXY=none 覆盖这一默认行为。

# 私有代理同时提供内部模块和公开模块，所有下载都走它
go env -w GOPROXY=https://proxy.corp.example.com
go env -w GOPRIVATE=*.corp.example.com

# none 表示这里不再让 GOPRIVATE 自动把模块排除出代理
go env -w GONOPROXY=none

# 私有路径不向公共校验数据库查询；内部代理可按组织策略提供校验服务
go env -w GONOSUMDB=*.corp.example.com

如果私有代理只服务内部模块、公开模块仍由公共代理提供，可以把代理列表写成私有代理、公共代理和直连的组合。代理返回 404 或 410 时，逗号分隔的下一项才会接管；如果代理返回其他错误码，Go 通常不会继续按逗号回退，这一点对排查“为什么没有走到公共代理”很关键。

# 私有代理优先，找不到公开模块时再交给公共代理
go env -w GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org,direct
go env -w GOPRIVATE=*.corp.example.com

# 让私有模块不去公共 checksum 数据库；下载是否经过代理由上面的策略决定
go env -w GONOSUMDB=*.corp.example.com

按症状判断到底是哪一层出问题

排查时先看配置，再看访问路径，最后看凭据。不要把所有错误都归因于 GOPRIVATE。

1. 变量没有生效：用 go env 查看当前执行用户的值。CI、容器和本机用户可能使用不同的 Go 配置文件。
2. 私有路径仍出现在公共服务请求中：检查路径模式是否命中，尤其是根域名与子域名是否分别覆盖；再检查是否有 GONOPROXY 或 GONOSUMDB 覆盖预期。
3. 代理返回 403 或认证错误：这是代理策略、账号或访问控制问题，不是把 GOPRIVATE 再写一遍就能解决。
4. 回退没有发生：核对代理返回的是 404/410 还是其他错误。逗号列表并不意味着所有错误都会自动尝试下一项。
5. 直连时卡在仓库访问：检查仓库 URL 发现、内部 DNS、证书和 Git 的非交互式凭据，不要直接全局关闭校验。

# 输出决策相关变量，便于在 CI 日志中复查配置；不要输出敏感凭据
go env GOPRIVATE GONOPROXY GONOSUMDB GOPROXY GOSUMDB GOVCS

# 只针对一个依赖观察下载过程，避免把整棵依赖树的无关日志混入排查
go mod download -x corp.example.com/payments/sdk@v1.2.3

-x 会输出执行的外部命令，日志可能包含仓库地址，因此共享日志前应按团队规则脱敏。它用于确认 Go 选择了哪类来源，不代表已经证明代码内容安全。

发布前可以保留的最小检查清单

• 私有模块前缀是否足够具体，是否误把整个平台的公开模块一起归为私有。
• 直连模式是否有可用的仓库读权限和非交互式凭据。
• 私有代理模式是否明确设置了 GONOPROXY 的覆盖关系。
• 私有模块是否通过 GONOSUMDB 或 GOPRIVATE 避免查询公共 checksum 数据库。
• 公开依赖是否仍保留团队需要的代理和校验策略，而不是被全局 GOSUMDB=off 一刀切。
• 排查日志是否移除了令牌、用户名、内部仓库路径之外不应公开的环境信息。

记住一个实用判断：下载失败先分“代理拒绝、仓库拒绝、路径发现失败”三类；校验失败再分“公共 checksum 不应访问、内部代理未提供校验、go.sum 不一致”三类。这样配置 GOPRIVATE 才是在收窄信息边界，而不是用一个环境变量掩盖所有依赖供应链问题。

相关问题

GOPRIVATE 会自动配置 Git 登录吗？

不会。它只影响 Go 对模块路径的分类和默认下载、校验决策，Git 的 SSH、HTTPS、凭据助手、证书和仓库权限仍需单独配置。

有私有代理还要设置 GOPRIVATE 吗？

通常仍建议设置，用于表达哪些路径属于私有，并作为校验策略的默认边界；同时按代理职责设置 GONOPROXY、GONOSUMDB。

为什么设置了 GOPRIVATE 仍然下载失败？

常见原因是路径模式没命中、代理返回了不可回退的错误、内部仓库发现入口不可用，或执行用户缺少仓库读权限。按配置、来源、认证三层分别检查更快。