Go 私有依赖校验和失败的代理配置

Go 拉取私有依赖时报校验和失败时，先不要把 \`GOSUMDB=off\` 当成万能开关。更稳妥的处理是：用模块路径匹配配置 \`GOPRIVATE\` 或 \`GONOSUMDB\`，再决定私有模块走公司代理还是直接访问 Git 仓库，最后补齐不会弹交互提示的凭据。

一句话判断：\`GONOSUMDB\` 解决“不要把这个模块交给公共校验和数据库”，\`GOPROXY\` 解决“模块从哪里下载”，Git 凭据解决“私有仓库是否允许当前进程读取”。三件事混在一起改，通常只会让错误更难定位。

本文依据 Go Modules Reference，官方文档：\`https://go.dev/ref/mod\`。示例只使用虚构域名 \`corp.example.com\`，不包含真实账号、Token 或仓库地址。

先看错误落在哪一层

我在 CI 里遇到过这样的现象：公开依赖可以下载，内部模块却在校验和阶段失败；换成关闭校验和后，又变成 Git 的认证失败。这个现象说明下载链路至少有三层，不能只盯着最后一行错误。

用 GOPRIVATE 和 GONOSUMDB 标出私有范围

如果所有以 \`corp.example.com\` 开头的模块都属于私有代码，最小配置可以先这样写。\`GOPRIVATE\` 会作为 \`GONOPROXY\` 和 \`GONOSUMDB\` 的默认值，因此不必为了同一组路径重复填写三次。

# 用模块路径前缀声明私有范围，避免把路径送到公共代理和校验和服务。
go env -w GOPRIVATE=corp.example.com

# 查看实际生效值，排查 CI 是否被旧环境变量覆盖。
go env GOPRIVATE GONOPROXY GONOSUMDB GOSUMDB GOPROXY

如果只想停止公共校验和查询、仍然希望私有模块由公司代理提供，可以把职责拆开：

# 私有模块仍可由内部代理下载，但不访问公共 checksum database。
go env -w GOPRIVATE=corp.example.com
go env -w GONOPROXY=none
go env -w GONOSUMDB=corp.example.com

# 这里的 none 表示不额外匹配模块路径，不等于关闭所有代理。
go env GONOPROXY GONOSUMDB

要注意，\`GONOSUMDB\` 只改变校验和数据库的匹配范围，不能替代 Git 登录，也不能让一个不存在的模块突然变得可下载。

再决定 GOPROXY 的下载路线

直接访问仓库与使用公司代理是两种不同的部署模型。直接访问适合已有稳定 Git 凭据的开发机或 CI；集中代理适合希望统一缓存、审计和权限的团队。

# 方案 A：公开模块走公共代理，私有模块命中后直接访问 VCS。
go env -w GOPROXY=https://proxy.golang.org,direct
go env -w GOPRIVATE=corp.example.com

# 方案 B：所有模块先走公司代理；是否回退由代理的 404/410 响应决定。
go env -w GOPROXY=https://proxy.corp.example.com
go env -w GONOSUMDB=corp.example.com

这里不要机械地同时写 \`GOPROXY=direct\` 和 \`GOPRIVATE\`。前者改变所有模块的下载入口，后者描述哪些路径需要私有策略。若公司代理返回 403，Go 通常不会把它当作“没找到”继续尝试后面的地址；这时应先检查代理权限与配置，而不是不断增加逗号后的回退项。

如果目标是“私有模块也必须经过公司代理”，可以用 \`GONOPROXY=none\` 覆盖 \`GOPRIVATE\` 对代理选择的默认影响；如果目标是“私有模块完全直连”，则保留默认的 \`GONOPROXY=corp.example.com\` 更直观。

最后补上不会卡住 CI 的凭据

配置匹配正确后，如果错误变成 Git 的认证失败，说明 Go 已经走到了仓库访问层。Go 调用 Git 时默认关闭交互式提示，因此 CI 中应使用受控的凭据注入方式，例如 CI 平台的凭据存储、短期令牌或 SSH agent；不要把密码直接写进 \`go env\`、\`go.mod\` 或文章里的命令。

# 只展示检查思路，不打印令牌内容，也不把凭据写入项目文件。
git config --global --get-regexp 'url\..*\.insteadOf|credential\.'

# 用环境变量确认 CI 能看到目标主机；实际令牌由 CI 凭据系统注入。
git ls-remote https://git.corp.example.com/team/private-lib.git HEAD

# 回到 Go 层查看路径匹配，避免把认证问题误判成 checksum 问题。
go env GOPRIVATE GONOPROXY GONOSUMDB GOPROXY GOSUMDB

复查时按这个顺序最省时间：先看模块路径是否匹配私有规则，再看下载请求落到哪个代理或 VCS，最后看该入口的凭据是否可用。不要在共享 CI 日志中输出 \`GIT_ASKPASS\`、Token 或带认证信息的 URL。

相关问题

只设置 GONOSUMDB，不设置 GOPRIVATE 可以吗？

可以，但两者职责不同。只想跳过公共校验和数据库时可以单独设置 \`GONOSUMDB\`；如果还要控制代理是否访问私有路径，通常使用 \`GOPRIVATE\` 或同时配置 \`GONOPROXY\`。

把 GOSUMDB 设为 off 能解决私有依赖失败吗？

它会关闭全局校验和数据库校验，范围过大，也会放弃公开模块的校验保障。优先用精确的私有路径匹配，只有明确理解风险和适用边界时才考虑全局关闭。

为什么 GOPRIVATE 配好了仍然提示认证失败？

因为路径匹配只改变代理和校验和策略，不会自动授予 Git 仓库读取权限。继续检查 CI 的 SSH agent、凭据助手或令牌权限，并确保访问过程不会等待交互输入。