Go GOPROXY=direct 访问私有模块时如何配合认证

把 GOPROXY 改成 direct，并不会自动给私有仓库“登录”。它只表示 Go 不再通过模块代理取包，而是直接调用模块路径对应的版本控制系统；真正的认证仍由 Git 的 HTTPS 凭据助手、CI 注入的凭据或 SSH 完成。配置私有模块时，通常要同时处理三件事：模块范围、下载路径、仓库认证。

GOPROXY=direct 只负责换路，认证要交给 Git

Go 模块请求可以经过代理，也可以直接访问版本控制系统。官方模块参考把 GOPROXY 的值分成代理 URL、direct 和 off：其中 direct 让 Go 直接与 VCS 通信。因此它不会读取一个神奇的 Go token，也不会替你绕过仓库权限。

可以先把职责记成一张小表：

先把私有模块范围写对，再谈 token 或 SSH

假设公司模块都位于 git.example.com/acme/，可以先在开发机或 CI 的环境配置中写出明确范围：

# 只把公司模块标记为私有，避免公共模块也被改道
go env -w GOPRIVATE=git.example.com/acme/*

# 让 Go 对匹配的模块直接访问版本控制系统
go env -w GOPROXY=direct

# 如果环境不允许访问公共校验服务，再关闭校验数据库
go env -w GOSUMDB=off

# 先确认 Go 实际读到的值，避免被 shell 或 CI 旧变量覆盖
go env GOPRIVATE GOPROXY GOSUMDB

GOPRIVATE 是范围匹配，不是凭据。它默认会为匹配的模块调整 GONOPROXY 和 GONOSUMDB 的行为；如果组织有内部代理，别机械地使用 GOPROXY=direct，也可以让私有模块走内部代理、公共模块走公共代理。GOSUMDB=off 只适合你明确知道校验服务不可达或组织已有替代校验方案的场景，不要把它当作认证修复开关。

让 Git 通过 HTTPS helper 或 SSH 提供凭据

模块路径最终落到 Git 仓库后，先不要急着重跑 Go。用与 Go 将要访问的同一个主机和路径做最小验证：

# 只验证远端是否可访问；不要把 token 写进命令行历史
git ls-remote https://git.example.com/acme/private-lib.git

# macOS 可使用系统钥匙串保存 HTTPS 凭据
git config --global credential.helper osxkeychain

Linux 可以选用系统的 libsecret 等安全 helper；CI 则应通过平台的 secret 注入短期凭据。Git 官方文档也列出了 cache、store 等 helper，但 store 会把凭据以明文形式保存在磁盘，不适合共享机器。若团队统一使用 SSH，可把私有主机的 HTTPS 地址重写到 SSH 地址，再运行同样的 git ls-remote 验证。

# 让该主机的 HTTPS 仓库改用 SSH；只作用于匹配的主机
git config --global url."ssh://git@git.example.com/".insteadOf "https://git.example.com/"

# 验证 SSH 身份和仓库路径，成功后再回到 Go
git ls-remote ssh://git@git.example.com/acme/private-lib.git

不要把用户名、密码或 token 直接嵌进模块路径。它们容易进入 shell 历史、构建日志或错误信息，而且仓库地址变化时还会让凭据范围变得不可控。

遇到 404、认证失败和校验失败时按链路定位

这类问题最容易误判：错误文本里出现了模块名，并不代表模块下载阶段已经走到 Git。按下面顺序检查，通常几分钟就能分层：

# 只打印配置，不打印凭据内容
go env GOPRIVATE GOPROXY GONOPROXY GONOSUMDB GOSUMDB

# 先测试依赖下载，再观察错误属于代理、Git 还是校验阶段
go mod download -x git.example.com/acme/private-lib@v1.2.3

-x 适合在受控环境里观察 Go 调用了哪些外部命令；日志中若出现敏感 URL 或凭据片段，应在保存前脱敏。修复时也尽量只缩小或纠正匹配范围，不要为了“先跑通”给 token 添加整个组织的写权限。

相关问题

只设置 GOPROXY=direct，为什么仍然访问公共服务？

direct 改的是模块获取方式；如果私有模块范围、代理或校验相关配置没有匹配，仍可能在其他阶段看到公共服务请求。先检查四个 go env 值。

GOPRIVATE 能替代 Git 凭据吗？

不能。它只是匹配模块路径并调整代理、校验行为，仓库仍要通过 Git helper、SSH 或 CI 凭据完成认证。

GOSUMDB=off 是否能修复 403？

不能。它处理的是校验数据库访问；如果 git ls-remote 已经返回 403，应修复仓库权限或凭据范围。

最后可以把排查顺序固定为：先确认 GOPRIVATE 命中，再确认 git ls-remote 能访问，最后运行 go mod download。这样每一步只验证一个边界，认证问题就不会和代理、模块路径、校验服务混在一起。