Go 私有模块怎样配置校验例外

Go 私有模块需要排除公共校验数据库查询时，应把真实的私有模块路径前缀配置到 GONOSUMDB；如果同时希望私有模块绕过公共代理直连仓库，可使用 GOPRIVATE 作为默认分类。若私有模块必须经过企业代理，还要显式控制 GONOPROXY，避免默认继承导致代理被绕过。

不建议为了一个私有模块把 GOSUMDB 全局设为 off。更准确的选择是只为指定前缀设置例外，让公共依赖继续保留原来的校验数据库策略。下面比较“私有仓库直连”和“企业代理统一供包”两种场景，不涉及绕过仓库访问权限。

官方参考地址：https://go.dev/ref/mod。

先分清是公共校验查询还是仓库访问失败

考虑一个示例项目：公共依赖能下载，加入 git.example.com/team/toolkit 后失败。首先要判断失败发生在哪个服务：是校验数据库无法识别私有路径，还是 Git 仓库、代理服务返回无权限？这两类问题可能同时出现，但不能用同一个环境变量解决。

GONOSUMDB 是校验数据库的路径例外，不是仓库密码，也不会替代理生成权限。若错误已经来自私有仓库的认证或授权环节，应按组织允许的凭据机制处理，不要继续扩大路径匹配范围。

示例中的 git.example.com、modules.example.com 和版本号都只用于说明配置形态。它们不是可访问的企业服务，也不能替代自己项目实际的 go.mod 模块路径。

三个变量分别决定什么

可以把配置拆成两个独立判断：模块从哪里取，模块是否查询校验数据库。GOPRIVATE 提供私有模块的默认分类，GONOPROXY 和 GONOSUMDB 则分别覆盖这两个判断的匹配列表；覆盖是独立列表，不是自动在 GOPRIVATE 后追加一项。

Go 命令的私有代码配置说明给出了三个路径列表的继承与覆盖关系。配置前应看有效值，而不只看某一份脚本里写了哪一行；CI 注入、终端变量或用户级 Go 环境设置都可能参与最终结果。

私有模块直连时怎样配置

没有私有模块代理、构建机器可以按授权直接访问仓库时，采用直连方案。下列命令用进程环境变量限制影响范围，并把三项写全，使示例行为不依赖用户机器上是否已经保存过不同的 GONOPROXY 或 GONOSUMDB。

# 仅本次命令生效：将示例前缀替换为企业实际模块前缀。
# 私有前缀绕过代理并跳过校验数据库；公共模块仍走原有代理配置。
GOPRIVATE='git.example.com/team' \
GONOPROXY='git.example.com/team' \
GONOSUMDB='git.example.com/team' \
go mod download git.example.com/team/toolkit@v1.4.2

这里没有改写 GOPROXY，所以公共模块仍按已有配置下载。若另外两项尚未设置，通常只写 GOPRIVATE 就能表达相同的私有分类默认值；但在排查有历史配置的环境时，明确覆盖三项更容易看出当前选择。

匹配对象是模块路径前缀，不是 Git 克隆地址。模块若声明为 git.example.com/team/toolkit，就按这个路径设计范围，不要把 https://、用户名或 .git 后缀随意拼到列表里。多个范围使用逗号分隔，带通配符的值要引用，避免 shell 提前展开。

使用企业代理时为什么还要改默认继承

如果企业代理统一提供公共和私有模块，则目标是“私有模块仍走代理，但不查询公共校验数据库”。这时只加 GOPRIVATE 反而可能让私有路径走直连，需要阻止 GONOPROXY 的默认继承。

# 企业代理须能提供目标私有模块；此域名仅为占位示例。
# none 不匹配真实模块，显式阻止 GONOPROXY 从 GOPRIVATE 继承私有前缀。
GOPROXY='https://modules.example.com' \
GOPRIVATE='git.example.com/team' \
GONOPROXY='none' \
GONOSUMDB='git.example.com/team' \
go mod download git.example.com/team/toolkit@v1.4.2

这里的 none 是一个不匹配正常模块路径的模式值，不是企业代理名字。方案要求代理能够返回私有模块，并由受信任的代理及仓库管理机制保障供包；配置例外并没有创造新的公共校验记录。

GOPROXY 只列企业地址，是有意不设置公共回退。若企业代理之后追加公共代理，私有模块不存在或路径拼错时，某些回退响应可能让模块路径被送往公共服务。模块参考中的私有代理说明特别讨论了这种路径泄露风险。不要因为设置了 GONOSUMDB，就误认为公共代理也一定不会收到该路径。

按路径范围选择而不是关闭全部校验

校验例外的范围应当与仓库归属一致。只拥有团队命名空间的私有仓库，就优先精确到该命名空间；不应把托管平台整个域名都视为私有，否则无关公共模块也可能失去原来的公共校验数据库查询。

不查询校验数据库，不代表“不计算校验和”或“go.sum 可以删除”。已有记录与下载内容不一致时应调查依赖来源和版本管理，尤其不要为了让构建通过就删掉历史校验记录或覆盖不可变版本的内容。公共依赖仍应保持适合项目的认证策略。

采用哪种方案取决于网络与信任结构，而不是变量越多越好。直连减少代理依赖，却要求构建节点管理仓库连接与凭据；统一代理收拢下载来源，则把更多可用性和内容管理责任交给企业基础设施。

配置不生效时还需要区分的几个问题

设置 GOPRIVATE 后，为什么还是查校验数据库？

先看 GONOSUMDB 的有效值是否已经单独设置，导致它不再继承 GOPRIVATE；再核对实际模块路径和所写前缀是否匹配。不要只看某次 export 命令成功就认定构建子进程获得了相同环境。

# 读取当前构建进程的有效配置，不打印整个环境或凭据。
go env GOPRIVATE GONOPROXY GONOSUMDB GOSUMDB
# 若要查看 GOPROXY，先确认其中没有嵌入账号密码或令牌。
go help private

这些命令供读者在自己的构建环境中使用，本文没有运行下载或模拟私有仓库。可依据自己的真实错误区分数据库查询、代理响应、仓库认证与内容不一致，不把它们都归为“校验失败”。

是不是必须用 go env -w 才有效？

不是。进程环境变量适合 CI 或临时任务；go env -w 是持久化用户级默认设置，影响后续调用，使用前应记录原值。用 go env -u 删除的是该持久化默认项，不会清掉外层 shell 或 CI 正在注入的变量。具体行为见 go env 帮助。

GOINSECURE 能不能代替校验例外？

不能把它当作 GONOSUMDB 的替代品。它处理直接获取依赖时允许的不安全传输范围，不是配置私有模块校验数据库例外的工具；也不应为解决普通私有模块访问问题而降低传输保护。

最终可把选择压缩成一句话：先确定私有模块是否经过企业代理，再用尽可能窄的前缀配置校验数据库例外。下载来源、仓库权限、传输保护和 go.sum 记录各有职责，别用全局关闭校验把不同问题混在一起。