Go 私有模块拉取失败如何配置 GOPRIVATE

私有模块拉取失败时，先不要把 GOPROXY=off 或 GOSUMDB=off 当成万能开关。通常只需要让 GOPRIVATE 匹配真实的模块路径前缀，例如 git.example.com/team；它会默认让匹配模块不走公共代理，也不访问公共 checksum 数据库。公共依赖仍可沿用默认的 https://proxy.golang.org,direct。

官方地址：https://go.dev/ref/mod#private-modules

最小可行配置是先设置正确的私有路径前缀，再确认 Git 或私有代理本身能完成认证。GOPRIVATE 只负责判断哪些模块属于私有范围，不会替你创建账号、发放令牌或修复仓库权限。

先用三个指标分清是代理问题还是权限问题

排查时先记一条基线：公共代理请求次数、失败率、首次成功耗时。比如同一个私有模块连续执行 30 次下载，若公共代理请求仍出现且失败率接近 100%，优先怀疑路径没有匹配；若已经没有公共代理请求，但直连仍返回认证错误，问题就转到 Git 凭据、仓库权限或模块路径解析。

不要把完整令牌、密码或个人路径贴进日志，只保留模块路径前缀、GOPROXY 是否命中、错误类型和耗时分位数。

直连私有仓库时怎样设置 GOPRIVATE

假设公司模块路径都以 git.example.com/team 开头，可以把前缀写入 Go 的用户配置：

# 只把 team 前缀下的模块标记为私有，公共依赖仍按默认链路处理
go env -w GOPRIVATE=git.example.com/team

# 读取最终值，确认配置落到了当前用户的 Go 环境中
go env GOPRIVATE GOPROXY GONOPROXY GONOSUMDB

GOPRIVATE 是逗号分隔的 glob 列表。多个组织可以写成 git.example.com/team,code.example.net/internal；如果私有模块分布在多个子域名，也可以按官方文档使用类似 *.corp.example.com 的模式。匹配对象是模块路径，不是仓库首页 URL。

设置后，GONOPROXY 与 GONOSUMDB 默认继承 GOPRIVATE。直连方案一般不需要同时手工设置它们，也不需要为了私有模块关闭全局 GOSUMDB。

有私有代理时不要把 GOPRIVATE 当成唯一方案

如果团队有可信的私有模块代理，策略要改成“先访问私有代理”。可以使用私有 GOPROXY，并用 GONOSUMDB 指定不应交给公共 checksum 数据库的模块；是否设置 GONOPROXY，取决于这些私有模块是否需要绕过代理直连。

# 私有代理负责提供内部模块，公共模块也只从这个可信代理获取
export GOPROXY=https://proxy.corp.example.com

# 仅让内部路径跳过公共 checksum 数据库，不关闭全局校验
export GONOSUMDB=corp.example.com

# 查看当前 shell 的生效值，避免把临时 export 当成永久配置
go env GOPROXY GONOSUMDB GONOPROXY

若私有代理只服务内部模块，可以采用“私有代理、公共代理、direct”的回退列表，但逗号回退通常只针对 404 或 410；私有代理返回 403 等其他错误时，Go 不会继续访问后面的来源。

配置正确后还拉不下来，按这个顺序排查

1. 先看匹配：确认值是模块路径前缀，而不是仓库网页地址；多项值用逗号分隔。
2. 再看来源：直连场景保留默认 GOPROXY 即可，私有代理场景再配置可信代理。
3. 最后看认证：直连下载依赖 Git、SSH 或 HTTPS 凭据；Go 默认关闭交互式 Git 提示，凭据应提前配置在受控的 Git 凭据系统、.netrc 或团队允许的认证机制中。

# 只请求指定模块的版本信息，不把真实凭据放进命令行
go list -m -json git.example.com/team/payment

# 只验证该模块链路，避免用全量 tidy 放大排查范围
go mod download git.example.com/team/payment

如果错误从公共代理 404 变成 Git 认证失败，反而说明 GOPRIVATE 已经接管了来源选择；此时应修复仓库权限或 URL 解析，而不是继续扩大 GOPRIVATE 范围。

常见误区与边界

把 GOPRIVATE 写成仓库地址：它匹配模块路径，不需要 https://；.git 只有在模块路径本身包含它时才保留。

把所有依赖都标记为私有：过宽的模式会让公共模块绕过代理和 checksum 服务，增加直连负担并削弱可观察性。前缀尽量收敛到组织或团队边界。

把认证失败当成网络失败：GOPRIVATE 只改变来源选择。私有仓库仍要有读取权限，且最好让 Git 不需要交互输入密码；不要把凭据硬编码到 GOPROXY URL 中。

相关问题

设置了 GOPRIVATE 还需要设置 GONOPROXY 吗？直连私有模块时通常不需要，GOPRIVATE 默认作为二者的值；只有希望代理和 checksum 数据库采用不同范围时，才单独覆盖。

能不能直接把 GOSUMDB 设为 off？不建议用全局关闭来解决单个私有模块问题，优先用 GOPRIVATE 或 GONOSUMDB 精确限定范围。

为什么 GOPRIVATE 正确仍提示找不到仓库？这通常已经越过代理选择阶段，继续检查模块路径对应的仓库发现地址、Git 凭据、仓库读权限和 SSH/HTTPS 配置。

把排查压缩成一句话：先用准确的模块前缀配置 GOPRIVATE，再根据错误落点处理代理、checksum 或 VCS 认证；用公共代理请求次数、失败率和首次成功耗时记录改动结果。