Go GOSUMDB 怎样与私有模块配置配合

私有模块通常通过 GOPRIVATE 或更精确的 GONOSUMDB 排除公共校验数据库查询，同时保留 GOSUMDB 对公开模块的校验能力。如果私有依赖必须经过企业代理，还要单独决定 GONOPROXY，避免它继承 GOPRIVATE 后改为直连仓库。

官方文档地址：https://go.dev/ref/mod。下面的域名都是配置占位示例，命令未在本文环境执行，不代表已部署的企业服务。

先确定公开与私有模块的调用需求

先选清楚一种拓扑：私有模块由开发机直接访问代码仓库，还是统一交给企业模块代理。两种拓扑对“是否经过代理”的答案不同，但都可以让私有模块不向公共校验数据库查询。

假设模块路径前缀是 code.example.com/team，并且团队要求直接访问私有仓库，可以在 POSIX shell 当前会话中使用下面的配置。前提是 GONOPROXY 与 GONOSUMDB 没有其他显式设置；应先查看有效环境，再决定是否采用。

# 只读查看当前有效设置，先确认是否已有显式覆盖。
go env GOPROXY GOPRIVATE GONOPROXY GONOSUMDB GOSUMDB

# 当前shell示例：声明私有模块前缀，保留公共校验数据库。
export GOPRIVATE='code.example.com/team'
export GOSUMDB='sum.golang.org'

这里的私有前缀是模块路径前缀，不是带协议的 Git 克隆地址。不要写成 HTTPS URL，也不要在值中嵌入密码或令牌。GOPRIVATE 只声明模块分类与相关默认策略，不会自动完成仓库鉴权。

把几个环境变量的职责拆开

将配置看成两组接口，会更容易判断该改哪个参数：下载组决定模块从哪里来；校验组决定是否查询校验数据库。GOPRIVATE 给两个组提供默认的私有范围，但显式指定的 GONOPROXY 与 GONOSUMDB 会分别覆盖对应默认值。

这些前缀列表使用 glob 模式语义，可按实际命名规则配置多个范围。精确前缀比宽泛通配更容易解释：只有一个团队路径需要排除时，不应因为配置方便就把全部模块都排除。

另一个容易混淆的点是 go.sum。不向校验数据库查询，并不等于忽略项目中已有的哈希记录。已有哈希不一致时，仍需调查模块版本和来源，不应把关闭数据库当作消除哈希冲突的方法。

企业代理场景怎样调整参数

若企业代理同时提供公开与私有模块，而开发机必须统一使用它，就不能让私有前缀继续命中 GONOPROXY。下面显式指定一个不匹配本文示例模块前缀的值，保留私有分类与校验数据库排除范围，但让下载仍使用企业代理。

# 示例域名必须替换为团队实际维护并信任的企业代理。
export GOPROXY='https://modules.example.com'
export GOPRIVATE='code.example.com/team'

# 显式覆盖代理排除范围，让示例私有模块仍走企业代理。
export GONOPROXY='none'
# 只对私有前缀排除数据库查询，公开依赖继续使用GOSUMDB。
export GONOSUMDB='code.example.com/team'
export GOSUMDB='sum.golang.org'

这里的 none 用作不匹配本文正常模块路径的模式值，不是代理服务器地址。GONOSUMDB 的值仍是模块前缀，不能填写校验数据库地址。企业代理如何取得私有模块、如何鉴权与如何服务校验数据，由代理部署另行决定。

若再给 GOPROXY 添加公共回退地址，应评估私有模块路径是否会被发送到下一站。逗号连接的来源一般在前一站返回 404 或 410 时继续；竖线连接的回退范围更宽。内网代理上的私有路径拼写错误，也可能触发回退，因此“设置了第一个企业代理”并不自动保证路径不会外传。

遇到错误时按所属层处理

仓库鉴权失败属于访问层；代理返回错误属于下载层；数据库不可达属于校验查询层；模块哈希不一致则属于内容一致性问题。把所有错误都归结为 GOSUMDB，往往会让配置越改越宽。

实际排查时先保留错误中涉及的模块路径与版本，再对照有效配置。发现私有模块仍触发数据库查询，重点检查前缀是否匹配、GONOSUMDB 是否被旧配置显式覆盖，以及 CI 与本机是否使用相同环境。敏感模块名和内部地址不应直接粘贴到公开问题页。

不建议为了让私仓下载通过而把 GOSUMDB 全局设为 off。这样会让原本应查询数据库的公开依赖也失去这部分校验。另一方面，公共数据库并不能为不公开的私有模块提供对应记录，因此对私有范围单独配置排除是正常的职责划分。

配置迁移与常见问答

将配置从开发机迁入 CI 时，应明确由构建环境变量、容器环境还是 go env 的持久设置负责。示例中的 export 只作用于当前 shell 及其子进程；它不会写入项目 go.mod。团队应记录私有前缀和代理拓扑，避免构建脚本与个人持久配置相互覆盖。

GONOSUMDB 会让私有依赖绕过代理吗？

不会，它控制校验数据库查询。是否绕过代理由 GONOPROXY 控制。只想调整校验范围时，不应顺手改变模块下载来源。

设置 GOPRIVATE 后为什么企业代理没被使用？

在未显式覆盖 GONOPROXY 时，它默认使用 GOPRIVATE 的范围，命中的模块会直接从版本控制仓库获取。若团队要求统一代理，需像上面示例一样明确代理排除策略。

私有模块还需要提交 go.sum 吗？

私有范围排除数据库查询并不取消 go.sum 的作用。应按项目正常依赖管理规则维护记录；不要为了解决一次下载错误而删除已有哈希。内容冲突需要回到模块版本与来源调查。

GOSUMDB 配好后，是否每次构建都连接公共数据库？

不一定。已有 go.sum 记录、缓存以及代理是否镜像校验数据库都会影响实际访问。不能仅凭一次没有网络请求就断言配置没有生效。配置依据见 Go 官方模块参考的 Private modules、Privacy 与 Environment variables 小节。