Go 私有模块在 CI 里突然走代理：用 GOPRIVATE、GONOSUMDB 和 GOPROXY 分开排查

CI 里执行 go mod download，本地能过，流水线却像“突然走了代理”，通常不是 Go 随机改变了行为，而是模块路径没有命中隐私规则，或者代理、校验库和 Git 凭据被混在了一起。排查时先看访问边界，再决定是否改配置。

先给结论：没有私有代理时，用 GOPRIVATE=git.example.com/team 让私有前缀避开公共代理和公共 checksum 数据库；有私有代理时，保留清晰的 GOPROXY 顺序，用 GONOSUMDB 控制校验范围，不要为了“能下载”全局关闭 GOSUMDB。

先确认 Go 到底访问了哪个来源

先在 CI 的安全日志中输出配置，不要输出令牌：

go env GOPROXY GOPRIVATE GONOPROXY GONOSUMDB GOSUMDB
go env GOMODCACHE
go mod download -x

GOPROXY 是按顺序尝试的代理列表，默认是 https://proxy.golang.org,direct。逗号分隔时，代理返回 404 或 410 才会进入下一项；超时、403 等其他错误可能直接终止，所以“代理失败后没有直连”并不一定是 direct 写错。把日志先分成来源、校验、版本库三层，后面的改动才不会互相覆盖。

把私有前缀交给 GOPRIVATE

变量匹配的是模块路径前缀，不是 Git 平台上的项目昵称。假设模块路径为 git.example.com/infra/logkit，可以在 CI 中设置：

export GOPRIVATE=git.example.com/infra
go env -w GOPRIVATE=git.example.com/infra

GOPRIVATE 会作为 GONOPROXY 和 GONOSUMDB 的默认值。也就是说，命中该模式的模块不会被送到公共代理，也不会交给公共 checksum 数据库。若公司有多个顶级前缀，用逗号分隔，例如 *.corp.example.com,git.example.com/infra。模式过窄会继续泄露或访问失败，模式过宽则可能把本来能复用公共代理的模块都改成直连，先按真实模块路径验证匹配范围。

按代理架构选择 GONOPROXY 与 GONOSUMDB

两种常见架构不要混配。若没有私有代理，保留默认 GOPROXY，用 GOPRIVATE 让私有模块直连版本库：

GOPROXY=https://proxy.golang.org,direct
GOPRIVATE=git.example.com/infra

若私有代理只服务私有模块，可写成：

GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org,direct
GONOSUMDB=git.example.com/infra

这里通常不要再设置 GONOPROXY，否则 Go 会绕过本来应该承载私有模块的企业代理。反过来，如果企业代理承载全部模块，官方建议让 GOPROXY 只指向该代理，并设置私有前缀的 GONOSUMDB。注意：代理返回 403、500 或网络超时，不会像 404/410 那样自然回退；这更像代理策略或服务可用性问题，而不是简单的私有路径未命中。

在 CI 里用非交互凭据复查

如果日志已经证明路径匹配正确，剩下多半是版本库权限或认证方式。直接访问私有仓库时，Go 会调用 Git，并默认把 GIT_TERMINAL_PROMPT 设为 0；这能避免流水线卡住，但也意味着没有预置凭据时会很快失败。给 CI 账号只读权限，确认 HTTPS 或 SSH URL 与凭据策略一致，再执行：

GIT_TERMINAL_PROMPT=0 go mod download
go list -m all

凭据应由 CI 的密钥注入、GOAUTH 或 Git 的非交互配置提供，避免把用户名密码直接写进 GOPROXY，因为环境变量可能进入日志。最终可用下面的判断表收口：

摘要：先用 go env 和 go mod download -x 确认来源；没有私有代理时优先设置 GOPRIVATE；有私有代理时再拆开考虑 GONOPROXY 与 GONOSUMDB。只关闭全部 checksum 校验，既不能修复权限，也会丢失公共依赖的可重复验证。

相关问题

GOPRIVATE 和 GONOPROXY 必须同时设置吗？不必须。GOPRIVATE 默认提供两者的匹配值，只有企业代理架构需要特殊区分时才单独设置。

为什么 GOPROXY 写了 direct 仍然失败？先看前一个代理返回的状态。逗号列表只对 404/410 回退，403、超时等错误可能是终止错误。

CI 中能不能直接设置 GOSUMDB=off？不建议作为私有模块的通用修复。优先用 GOPRIVATE 或 GONOSUMDB 精确排除私有前缀，保留公共模块的校验能力。

本文事实依据：Go Modules Reference：Private modules。