Go GOPROXY=direct 为什么仍然无法拉取私有依赖

设置了 GOPROXY=direct 后仍然拉不到私有依赖，通常不是 direct 失效，而是把“下载来源”“私有范围”“仓库认证”三个问题混在了一起。direct 只要求 Go 直接联系模块对应的版本控制仓库；它不会替你填写 Git 凭据，也不会自动修正模块路径。

官方文档：https://go.dev/ref/mod

先确认模块路径和仓库地址能对应，再配置 GOPRIVATE，最后排查 Git 认证与 GOVCS。如果公司有可信的私有模块代理，使用代理方案通常比所有依赖都设置为 direct 更容易维护。

先理解 GOPROXY=direct 改了什么

Go 默认会先访问模块代理，再根据情况直接访问仓库。把它设为 direct 后，模块下载阶段不再向代理请求模块元数据，而是根据模块路径寻找版本控制仓库。它只改变“从哪里找”，不改变“仓库是否允许你读”。

# 查看当前生效的模块下载相关配置
go env GOPROXY GOPRIVATE GONOPROXY GONOSUMDB GOPROXY GOSUMDB GOVCS

# 只在当前命令中直接访问版本控制仓库，便于排查配置影响
GOPROXY=direct go mod download example.corp/team/payment@v1.2.3

如果错误中出现 repository not found、authentication required 或 SSH/HTTPS 凭据提示，说明请求已经走到了仓库访问层；继续反复修改 GOPROXY 没有帮助。若错误包含公共代理或校验和服务域名，再检查私有范围配置。

按路径范围配置 GOPRIVATE

GOPRIVATE 是私有模块路径的匹配规则，通常写模块路径前缀，而不是写仓库网页地址。它默认影响 GONOPROXY 与 GONOSUMDB：匹配的模块不通过公共代理，也不提交到公共校验和数据库。

# 用公司模块前缀覆盖所有团队仓库
go env -w GOPRIVATE=*.corp.example.com

# 多个组织使用逗号分隔；不要把访问令牌写进环境变量值
go env -w GOPRIVATE=*.corp.example.com,github.com/acme-private

# 只有在代理与校验和策略不同的时候，才单独拆开配置
go env -w GONOPROXY=*.corp.example.com
go env -w GONOSUMDB=*.corp.example.com

最常见的错误是把 GOPRIVATE 写成项目首页，或只写仓库名而没有覆盖实际 module path。例如 go.mod 中的 module git.corp.example.com/platform/payments，就应匹配 git.corp.example.com 或更具体的前缀。匹配范围不对时，Go 仍可能把私有路径交给公共服务，或者无法按预期跳过代理。

分别排查 Git 认证与仓库发现

私有依赖的直接下载至少经过两个独立环节：先由模块路径定位仓库，再由 Git 客户端完成读取。可以按下面的证据顺序排查，不要先修改一整组环境变量。

# 只查看 Git 的远端解析和认证结果，不把凭据打印到日志
git ls-remote https://git.corp.example.com/platform/payments.git

# 检查 Go 对私有模块的路径匹配结果
go env GOPRIVATE GONOPROXY GONOSUMDB GOVCS

这两条命令的作用是把 Go 层问题缩小为“仓库本身不可读”还是“Go 配置没有命中”。不要用 GOSUMDB=off 作为万能修复；它会放弃所有未在 go.sum 中的模块校验，私有范围应优先用 GOPRIVATE 或 GONOSUMDB 精确表达。

选择直接拉取或企业代理方案

个人或小团队可以采用“公共依赖走代理、私有依赖直连”的组合；如果公司已经运行可信的私有模块代理，则应让代理承担私有仓库访问，开发者只配置代理地址和私有校验和范围。

# 私有依赖直连，公共依赖仍使用默认代理
GOPROXY=https://proxy.golang.org,direct
GOPRIVATE=*.corp.example.com

# 私有代理优先，公共代理作为后备；由代理决定私有仓库的读取权限
GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org,direct
GONOSUMDB=*.corp.example.com

使用逗号时，前一个代理返回 404 或 410 才会继续后备地址；权限拒绝、服务错误等通常应先修复代理本身。使用私有代理时不要随意设置 GONOPROXY，否则可能绕过企业代理，把私有路径重新暴露给直接访问流程。

最后可以把排查结果压缩成四项清单：

1. module path 是否与仓库根路径和版本标签一致；
2. GOPRIVATE 是否覆盖实际私有前缀；
3. 当前 Git 客户端是否有读取权限，且认证可在非交互环境工作；
4. GOVCS、代理返回码和校验和策略是否与团队方案一致。

相关问题

GOPRIVATE 配了还要设置 GONOSUMDB 吗？

多数情况下不需要，GOPRIVATE 默认同时影响两者。只有代理范围和校验和范围不同，或团队需要更细粒度策略时，才单独设置。

GOPROXY=direct 能解决 403 吗？

不能直接解决。403 可能来自企业代理、代码托管平台权限或网络入口；先确认请求实际到达哪一层，再修复对应权限或代理配置。