Go private module 校验失败时如何区分 GOPRIVATE 与 GOPROXY

私有模块报错时，先记住一句话：GOPRIVATE 决定哪些模块算私有，GOPROXY 决定从哪里下载，GONOPROXY 与 GONOSUMDB 才是对代理和校验库的细分覆盖。如果错误来自 proxy.golang.org，优先看代理路径；如果错误来自 sum.golang.org 或出现 checksum mismatch，再看校验配置；已经走到 Git 仓库后的 401/权限失败，则是凭据问题。

官方参考地址：https://go.dev/ref/mod。下面的示例使用虚构的 git.corp.example.com，不会暴露真实仓库或令牌。

先查看实际生效的模块环境

我排查这类问题时，第一步不是改配置，而是确认 go 命令真正读到的值。IDE、shell、CI 容器可能使用不同的用户配置，文件里写过不代表当前进程已经生效。

# 中文注释：只查看模块下载与校验相关变量，不打印凭据文件内容
go env GOPRIVATE GOPROXY GONOPROXY GONOSUMDB GOSUMDB

# 中文注释：查看当前持久化的私有模块匹配规则
go env GOPRIVATE

重点看五个值是否互相矛盾：GOPRIVATE 是否覆盖真实模块前缀，GOPROXY 是否仍指向公共代理，是否有人把 GONOPROXY 写成了不适用的模式，以及 GOSUMDB 是否被 CI 强制设为 off。查看环境时不要把 .netrc、SSH 私钥或访问令牌贴进日志。

先把四个变量放回各自职责

GOPRIVATE 接受以逗号分隔的 glob 模式，匹配模块路径前缀。匹配后，Go 默认把这类模块视为不应请求公共代理或公共 checksum database 的代码。它解决的是“这个模块属于哪类访问范围”，不是“公司代理的 URL 是什么”。

GOPROXY 是下载模块版本信息、go.mod 和 zip 的来源列表，可以写代理 URL、direct 或 off。逗号分隔时，只有当前代理返回 404/410 才继续下一个；这和认证失败、网络超时不是一回事。

GONOPROXY 只覆盖“是否绕过代理”，GONOSUMDB 只覆盖“是否绕过 checksum database”。例如企业已经部署了内部模块代理，可以保留私有匹配，但让私有模块继续交给内部代理：

# 中文注释：私有模块仍按域名匹配，并统一交给企业代理下载
go env -w GOPRIVATE=git.corp.example.com
go env -w GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org,direct
go env -w GONOPROXY=none

# 中文注释：只让企业域名模块不访问公共校验库，公共模块仍按默认策略校验
go env -w GONOSUMDB=git.corp.example.com

这里的 none 是一个配置语义：不要因为 GOPRIVATE 而绕过代理。它不等于把任何敏感信息写入代理，也不替代仓库认证。

按错误位置判断该改哪个变量

最常见的误判是：看到“私有模块下载失败”就设置 GOPROXY=direct。如果 GOPRIVATE 没匹配到真实路径，直连也只是把请求转到一个没有权限的 VCS 地址；如果匹配已经正确，剩下的 401 往往就是凭据、仓库权限或代理认证问题。

为企业代理选择最小覆盖项

如果公司代理能够访问私有仓库，配置重点通常是“私有模块走内部代理，公共模块仍有可用回退”，而不是所有依赖都直连。若只有校验库策略需要调整，优先写 GONOSUMDB，不要扩大 GOPRIVATE 的范围。

# 中文注释：用当前配置复查目标模块的代理与校验边界
go env GOPRIVATE GOPROXY GONOPROXY GONOSUMDB GOSUMDB

# 中文注释：下载命令只针对目标模块，错误位置更容易对应配置
go mod download git.corp.example.com/team/payment

# 中文注释：检查模块缓存完整性，不把它当作凭据检查
go mod verify

go mod verify 关注模块缓存内容与记录的完整性，不能证明仓库账号有权限。反过来，仓库已经能认证，也不能说明 checksum database 或 go.sum 策略正确。这几个结果要分开记录，排障才不会在配置之间来回试错。

常见问题

设置了 GOPRIVATE，为什么仍然下载不到私有模块？

先确认模式真的匹配模块路径，再看是否被 GONOPROXY=none、企业代理认证或 VCS 凭据覆盖。GOPRIVATE 不会自动创建仓库账号，也不会替你配置 SSH。

GOPROXY 设置成 direct 就一定能解决吗？

不一定。它只改变下载来源，不能修复仓库权限、模块路径错误或 checksum 不一致，而且会让所有模块都倾向于直连。更适合先用匹配规则缩小范围。

GOSUMDB=off 可以长期放在 CI 吗？

除非团队明确接受失去公共校验库保护的风险，否则不建议全局关闭。对私有模块优先使用准确的 GONOSUMDB 或 GOPRIVATE 模式，并保留公共依赖的校验。

为什么要看 go.sum，而不是只看环境变量？

环境变量决定校验路径，go.sum 保存主模块已记录的哈希。checksum mismatch 发生时，两者都可能正确，真正需要查的是下载内容、版本和代理是否提供了不同文件。

把这类故障拆成“模块是否私有、从哪里下载、由谁校验、仓库能否认证”四个问题，通常只需要改一个匹配规则或一个覆盖变量。配置越窄，公共依赖的默认保护越容易保留下来。