Go 私有模块下载的 GOPRIVATE 配置边界

GOPRIVATE声明哪些模块路径前缀属于私有范围，并为GONOPROXY和GONOSUMDB提供默认匹配规则；它不提供仓库账号、Token或SSH密钥。私有模块下载要分开配置“从哪里下载”“是否访问公共校验数据库”和“用什么身份读取”，不能靠一个变量包办。

Go模块官方文档：https://go.dev/ref/mod

先选定直连仓库还是公司代理

下面用一个简化接入任务说明：应用依赖公司团队下的一个私有模块。文中的git.example.test、modules.example.test和版本v1.2.3均为教学占位，不是真实入口或已经存在的版本；执行前必须替换成组织提供的模块路径、代理地址与可访问版本。本文不会访问这些示例地址，也不会修改读者机器配置。

如果公司没有提供私有模块代理，通常让私有范围走版本控制仓库，公开模块仍走原有代理。如果公司要求统一从内部模块代理下载，就不要让私有范围被GONOPROXY匹配后绕开它。先确定架构，再填变量，能少走很多“已经登录仓库却仍失败”的弯路。

用临时环境完成直连配置

下面是POSIX shell的完整示例。子shell中的export只影响括号内命令，退出后不会持续改变当前终端；它也没有使用go env -w写入用户级配置。

(
  # 替换成组织实际使用的模块路径前缀，不是https仓库URL
  export GOPRIVATE='git.example.test/team'
  # 显式表达本示例的直连与校验数据库策略，避免继承不相容的旧值
  export GONOPROXY='git.example.test/team'
  export GONOSUMDB='git.example.test/team'

  # 公共模块保留默认代理回退方式；私有匹配范围走直连
  export GOPROXY='https://proxy.golang.org,direct'
  # 替换模块与版本后再执行；该命令会下载到本机模块缓存
  go mod download 'git.example.test/team/ledger@v1.2.3'
)

这里有意显式设置两个细分变量，便于展示其边界。在没有额外覆盖的简单环境中，它们可以继承GOPRIVATE，不必重复填同一个值。若机器已设置了不同的GONOPROXY或GONOSUMDB，只改GOPRIVATE就不能假定旧覆盖值自动消失。

匹配内容是模块路径前缀及其glob规则，不是仓库网页URL、SSH克隆URL，也不是本地文件夹名。不要填https://开头的登录页；团队路径也应与go.mod中的module声明及实际依赖路径对应。多个私有范围使用逗号分隔，避免用过宽的通配符把公开模块也一起纳入私有策略。

公司代理服务私有模块时怎样调整

假设组织的受信任内部代理提供应用所需的全部公开与私有模块，可以用下面的另一套临时配置。它是替代方案，不是追加到上一组命令之后的步骤。

(
  # 示例地址须替换为组织批准的内部模块代理
  export GOPROXY='https://modules.example.test'
  export GOPRIVATE='git.example.test/team'
  # none不匹配正常模块路径，避免私有前缀默认绕过内部代理
  export GONOPROXY='none'
  # 私有模块不向公共校验数据库查询
  export GONOSUMDB='git.example.test/team'

  # 先按内部代理要求配置非交互凭据，再下载授权范围内的模块
  go mod download 'git.example.test/team/ledger@v1.2.3'
)

GONOPROXY=none不是“不用代理”，而是此处不让正常模块路径命中“跳过代理”的列表，因此遵循GOPROXY。GONOSUMDB控制的是另一条查询边界，不能拿它代替GONOPROXY。公司代理未收录某依赖时，应该根据其服务范围处理，而不是无条件追加所有外部回退地址。

代理列表中逗号和竖线的回退语义也不同：逗号通常只在前一来源返回404或410时回退，竖线会在其他错误时也继续。私有路径若因拼写错误触发外部回退，可能被发送到外部来源。不要把“能下载到”为唯一目标，更不要把竖线当成普遍修复超时的方法。

凭据属于哪一层

内部代理的HTTP凭据可以按组织要求交给.netrc或工具链支持的GOAUTH机制。使用GOAUTH前应核对本机Go版本及go help goauth支持范围；Go 1.24起提供相关能力，不能把它写成所有旧版本都有的配置。Go命令的HTTP凭据配置，也不等于替所有Git或SSH连接建立登录状态。

直连模式下，Git自己处理仓库认证。应配置为在CI或构建用户下不依赖交互输入，授予所需仓库的最小读取权限。Go默认调用Git时会禁用交互提示；在个人终端能弹窗登录，不代表无交互构建也能成功。HTTPS与SSH使用的凭据链不同，只有组织明确要求时才按实际仓库范围设置协议映射，不做全局粗放替换。

不要把Token写进go.mod、源码、示例URL、命令行或可公开的流水线日志。密钥应通过组织的秘密管理与凭据存储提供，并注意临时文件权限和有效期。本文不展示任何真实密钥，也不建议通过关闭TLS验证、扩大仓库权限来处理下载问题。

下载结果应该按哪类问题判断

在获授权且已替换占位值的环境中运行下载命令后，先看失败来自哪一层：请求外部代理意味着模块匹配策略可能不符；代理返回未授权意味着应检查该代理凭据；Git提示无法读取则要检查仓库地址、权限或非交互认证。不是每个失败都应该继续扩大GOPRIVATE。

还应区分缓存与网络：本机已有模块缓存时，下载命令可能不需要重新拉取全部内容，因此一次成功并不证明全新CI环境必然具备同样的网络和凭据。不要为了排查就删除共享模块缓存；需要独立环境时应按组织开发规范安排，而不是把清理大目录当作常规前置动作。

常见问题速查

设置GONOSUMDB后还保留go.sum吗？

需要。跳过公共校验数据库查询不等于删除本地go.sum或关闭所有内容一致性检查。不要把私有依赖接入写成GOSUMDB=off的全局开关。

GOPROXY=direct是不是等于GOPRIVATE？

不是。前者让模块下载走直连来源，影响范围与私有前缀声明不同；后者还能为两个细分规则提供默认值。仅把全部模块切到direct，也不会自动赋予仓库访问权限。

为何本机配置有效，CI仍失败？

CI运行用户的环境、凭据存储、网络和模块缓存可能不同。把无秘密的路由规则与秘密凭据分别注入，不要依赖某台开发机上残留的用户级状态。

私有模块接入最小化之后，就是三份明确约定：哪些路径属于私有范围、它们走哪个来源、该来源接受什么授权。GOPRIVATE解决第一份约定的默认规则，另外两份仍要独立落实。