Go 私有模块下载失败怎么排查：GOPRIVATE、代理和校验和的最小配置

Go 拉取私有模块失败时，先不要急着反复更换令牌或在本机关闭所有校验。多数情况下，模块路径还没走到你的代码仓库，就已经被公共代理或公共校验服务处理了。把私有模块前缀标进正确的环境变量，再确认团队究竟采用直连还是私有代理，通常就能把问题缩小到认证、网络或路径这三类。

最小可用做法是用 GOPRIVATE 标记私有模块前缀；它默认会同时影响代理绕过和公共校验服务绕过。只有在团队部署了受信任的私有代理时，才把 GONOPROXY 与 GONOSUMDB 拆开配置；不要为了一个私有模块把 GOSUMDB 全局设为关闭。

先区分：模块是被代理挡住，还是仓库拒绝访问

私有模块的模块路径是排障起点。例如项目依赖 git.example.internal/platform/ledger，Go 会按模块路径和当前的代理策略去查找版本。默认配置下，Go 会先使用模块代理；对于不该公开请求的路径，这会带来两类看似相近的报错：代理侧找不到模块，或者公共校验服务无法为私有内容提供校验记录。

先在出错项目目录执行下面两条命令，结果比猜测更有用。第一条展示实际生效的模块策略，第二条只下载一个明确版本；不要在日志里粘贴访问令牌、带签名的仓库地址或内部凭据。

go env GOPROXY GOPRIVATE GONOPROXY GONOSUMDB GOSUMDB
go mod download git.example.internal/platform/ledger@v0.8.0

如果下载请求仍然明显经过公共代理，重点检查 GOPRIVATE 是否写成了仓库 UI 的完整地址，或遗漏了实际模块路径中的上级前缀。若请求已直连到仓库却被拒绝，再检查当前环境是否具备该仓库的正常访问权限、Git 客户端是否能在同一网络下访问，以及模块的 go.mod 声明是否与依赖路径一致。

没有私有代理：用一条前缀规则走直连

团队没有部署私有模块代理时，最紧凑的配置是只声明私有模块前缀。官方模块文档说明，GOPRIVATE 会成为 GONOPROXY 与 GONOSUMDB 的默认值：匹配的模块不经模块代理下载，也不向公共校验服务查询。

go env -w GOPRIVATE=git.example.internal
go env GOPRIVATE GONOPROXY GONOSUMDB
go mod download git.example.internal/platform/ledger@v0.8.0

这里的边界只有一个：git.example.internal 应当是团队私有模块的共同路径前缀。如果另一个业务线使用 code.example.internal，需要按实际模块前缀追加匹配规则。不要把某个具体模块版本写成长期规则，也不要把无关的公共域名加入私有列表，否则会让本应经过正常代理与校验的依赖失去保护。

有私有代理：把“下载来源”和“公共校验”分别看待

私有代理存在时，配置取决于它的覆盖范围。若它只缓存或服务私有模块，公共模块仍可以保留公共代理与直连后备；私有模块应避免查询公共校验服务。最小策略可以写成下面这样，示例中的地址仅表示团队内部代理。

go env -w GOPROXY=https://modules.example.internal,https://proxy.golang.org,direct
go env -w GONOSUMDB=git.example.internal
go env GOPROXY GONOPROXY GONOSUMDB
go mod download git.example.internal/platform/ledger@v0.8.0

这组配置与直连模式不同：没有设置 GONOPROXY，因此私有模块仍可以交给团队的私有代理处理；GONOSUMDB 只阻止私有路径请求公共校验服务。若企业代理统一服务公共和私有模块，通常把 GOPROXY 固定为这个受信任来源，再单独声明私有路径不使用公共校验服务即可。不要习惯性把 GONOPROXY 也设上，否则会绕开本应承担权限、缓存或审计职责的私有代理。

一张表看清最常见的配置误区

提交前做两个小验证

配置完成后，不必立刻清空整个模块缓存。先确认环境值，再针对一条私有依赖运行下载命令；成功后再执行项目自己的测试或构建流程。这样能避免代理问题、仓库权限问题和编译问题混在一段超长日志里。

go env GOPRIVATE GONOPROXY GONOSUMDB
go mod download git.example.internal/platform/ledger@v0.8.0

最后要保留一个安全边界：GOSUMDB 全局关闭会让所有未知模块放弃公共校验带来的可重复下载保障。私有模块的确需要按路径排除公共校验，但公共依赖仍应使用团队允许的代理与校验链路。把规则收窄到实际私有前缀，后续迁移仓库或排查供应链问题时会轻松很多。

相关问题

GOPRIVATE 和 GONOPROXY 一定要同时设置吗？

不一定。没有私有代理时，GOPRIVATE 默认会影响 GONOPROXY，通常已经足够；有受信任私有代理时，往往只需要保留代理路径并设置 GONOSUMDB，避免把私有下载绕开代理。

为什么不建议直接关闭 GOSUMDB？

它会影响所有模块的公共校验，而不只是私有模块。对私有路径使用 GOPRIVATE 或 GONOSUMDB 能把影响限定在需要的范围内。

设置后还提示仓库没有权限怎么办？

这说明请求大概率已到达正确的下载来源，接下来应按团队授权方式检查仓库访问、网络连通性和模块路径声明；不要把权限错误误判成代理配置问题。