Go GOPRIVATE 与 GONOSUMDB 配置重复时如何整理

如果配置里同时出现 GOPRIVATE=corp.example.com 和 GONOSUMDB=corp.example.com，通常不是两个独立需求，而是同一范围被写了两遍。Go 会把 GOPRIVATE 默认用于 GONOPROXY 和 GONOSUMDB；只有当校验数据库的跳过范围与“私有模块范围”不一致时，才需要单独保留 GONOSUMDB。

官方资料：https://go.dev/ref/mod

先把 GOPRIVATE、GONOPROXY、GONOSUMDB 分开

这三个变量都接受逗号分隔的模块路径前缀模式，但控制的是不同决策。GOPRIVATE 表示哪些模块路径应被视为私有，并且默认成为 GONOPROXY 与 GONOSUMDB 的值；GONOPROXY 决定哪些模块不走代理，GONOSUMDB 决定哪些模块不向公共 checksum database 请求校验。

因此，看到两行相同配置时，先不要按“变量越多越安全”处理。要问的是：当前团队需要改变下载来源、校验来源，还是两者都需要改变？

用模块路径前缀表达私有范围

配置对象是 Go module path，而不是代码托管平台的网页 URL。比如公司的模块都以 corp.example.com/ 开头，可以把这个前缀作为匹配范围：

# 让 Go 把公司模块识别为私有，并默认避开公共代理与校验库。
go env -w GOPRIVATE=corp.example.com

# 查看持久化后的值，避免只检查当前 shell 的临时环境。
go env GOPRIVATE GONOPROXY GONOSUMDB

这里的注释说明了两个不同动作：go env -w 写入 Go 的持久化配置，go env 读取 go 命令实际看到的值。不要只看 CI 配置文件或个人 shell 脚本，因为后者可能覆盖前者。

完全重复时，GONOSUMDB 可以删除

假设项目使用私有仓库直连，所有私有模块都以同一个前缀开头：

# 直连私有模块：GOPRIVATE 已提供默认的代理和校验跳过范围。
go env -w GOPRIVATE=*.corp.example.com

# 只有在校验范围需要不同于私有模块范围时，才额外设置 GONOSUMDB。
# 本场景没有额外范围，所以不重复写 GONOSUMDB。
go env GOPRIVATE GONOPROXY GONOSUMDB

在这种情况下，显式写 GONOSUMDB=*.corp.example.com 通常只是把默认值再写一遍。删除它可以减少配置漂移，也能让后来排查的人更容易看出：三个决策目前使用同一个私有范围。

三种重叠关系决定整理方式

匹配是按模块路径模式判断的，不是按“后写的变量覆盖前写的变量”理解。GONOSUMDB 并不会把 GOPRIVATE 改名或清空；它只是在校验数据库这一项上提供更细的匹配范围。

私有代理场景不要误把 GONOSUMDB 当成 GONOPROXY

如果公司有可信的内部模块代理，并且希望公共模块也通过该代理获取，配置思路与“私有仓库直连”不同：

# 统一代理承载公共模块和私有模块。
go env -w GOPROXY=https://proxy.corp.example.com

# 私有模块不应向公共 checksum database 查询，但仍然从内部代理下载。
go env -w GONOSUMDB=corp.example.com

# 这里不设置 GONOPROXY，避免把私有模块强制改成直连仓库。
go env GOPROXY GOPRIVATE GONOPROXY GONOSUMDB

这是最容易整理错的地方：GOPRIVATE 默认还会影响 GONOPROXY。如果内部代理确实负责私有模块，就应使用更精细的 GONOPROXY=none 或者不让 GOPRIVATE 产生错误的直连语义，具体取决于团队的代理架构。核心原则是：下载是否走代理，与是否向公共校验库查询，是两条独立决策链。

最后用 go env 检查实际生效配置

整理文件后，检查 Go 命令最终读取的值，而不是只检查某一个配置来源：

# 一次性打印与私有模块解析相关的最终配置。
go env GOPROXY GOPRIVATE GONOPROXY GONOSUMDB GOSUMDB

# 只清除明确不再需要的显式值，避免误删团队共享配置。
go env -u GONOSUMDB

go env -u 适合清除 Go 配置文件中的显式值，让变量回到默认关系；它不会替你修改 CI 注入的环境变量。若输出仍然和预期不同，继续检查流水线变量、容器启动参数和 shell profile，而不是继续叠加一行配置。

常见问题

GOPRIVATE 设置后还要不要设置 GONOSUMDB？

如果两者范围完全相同，通常不需要。GOPRIVATE 默认提供 GONOSUMDB 的匹配范围；只有校验跳过范围需要独立调整时才保留后者。

GONOSUMDB 会让私有模块改走直连吗？

不会。它只控制 checksum database 校验请求。是否绕过模块代理由 GOPRIVATE、GONOPROXY 和 GOPROXY 共同决定。

为什么内部代理场景经常不设置 GONOPROXY？

因为内部代理可能正是私有模块的可信下载入口。此时把私有模块强制直连会绕开代理，和组织的下载审计、缓存或权限策略冲突。