在团队协作或企业开发中，Go 模块的私有依赖管理是绕不开的配置点。默认情况下，go get 会把所有模块请求发送到公共代理 proxy.golang.org，并使用校验数据库 sum.golang.org 做完整性验证。当模块路径指向公司内部 GitLab、GitHub 私有仓库或自建 Gitea 时，公共代理既无法访问，也没有对应的版本信息，于是会出现 404、terminal prompts disabled 或 401/403 等错误。要打通私有模块访问，不是简单地在 go.mod 里加一个 replace 指令，而是要让 Go 工具链识别私有路径，并为 Git 提供无人值守的认证方式。本文从环境变量、认证协议、平台配置和常见故障四个层面展开。
核心环境变量：GOPRIVATE 与它的两个衍生变量
Go 模块系统提供了 GOPRIVATE 环境变量，用来声明哪些模块路径前缀属于私有仓库。一旦匹配成功，go 命令会自动跳过公共模块代理和公共校验数据库，直接通过版本控制系统拉取源码。GOPRIVATE 支持多个路径前缀，用英文逗号分隔，例如 go env -w GOPRIVATE=gitlab.ipipp.com,github.com/your-org。
除了 GOPRIVATE，还有 GONOPROXY 和 GONOSUMDB 两个更细粒度的变量。GONOPROXY 只控制是否绕过代理，GONOSUMDB 只控制是否跳过 sum.golang.org 校验。如果不设置这两个变量，它们会默认继承 GOPRIVATE 的值。因此在大多数私有仓库场景下，只需要配置 GOPRIVATE 即可。不过当你的私有模块依赖了公共模块，或者想对部分私有路径保留 sumdb 校验时，可以单独设置 GONOSUMDB 来精确控制。
值得留意的是，GOPRIVATE 的匹配规则是按路径前缀匹配，而不是正则，也不能写成通配符。例如 gitlab.ipipp.com 会匹配该主机下的所有模块路径，包括子组和子仓库。对于企业内网使用 IP 地址或者带端口的 Git 服务，同样可以写进 GOPRIVATE，但 Go 官方建议直接写主机名即可。配置后可用 go env GOPRIVATE 验证是否生效，必要时执行 go clean -modcache 清理缓存。
认证方式：HTTPS 访问令牌与 .netrc
私有模块路径被识别后，go get 会调用本机 Git 去拉取仓库。对于 HTTPS 协议，Git 需要提供一个不会交互式询问密码的凭据来源。最常见的做法是使用个人访问令牌，并通过 .netrc 文件写入登录信息。在 Linux 或 macOS 上，可以创建 ~/.netrc 文件，内容如下：
machine gitlab.ipipp.com login oauth2 password <your-access-token>
这里 login 可以是任意非空字符串，GitLab 推荐使用 oauth2，GitHub 则可以使用你的用户名或者直接写 x-access-token。需要注意的是 .netrc 文件的权限不能过于宽松，否则 Git 会拒绝读取，通常执行 chmod 600 ~/.netrc。Windows 系统下对应的文件路径为 %USERPROFILE%\_netrc，注意是下划线开头。
如果不想在磁盘上保存明文凭据，可以启用 Git 的凭证助手。执行 git config --global credential.helper store 后，第一次拉取时输入用户名和令牌，Git 会把凭据保存到 ~/.git-credentials。对于 macOS 可以使用 osxkeychain，Windows 可以使用 manager。但这种方式在 CI/CD 环境中不如 .netrc 稳定，因为凭证助手可能需要交互安装或依赖系统组件。
还要注意 Go 模块代理本身不会使用 .netrc。只有当请求绕过代理、直接访问 Git 仓库时，才会走 Git 的认证流程。所以必须确保环境变量设置正确，否则即使 .netrc 写得没问题，go get 仍然会先到公共代理查询而报错。
SSH 协议与 Git 配置重写
除了 HTTPS，很多团队更习惯使用 SSH 协议访问私有仓库。SSH 的优势是部署密钥可以按仓库或按环境分配，不依赖长期令牌。要让 Go 模块走 SSH，需要在 Git 配置里做 URL 重写。假设模块路径为 gitlab.ipipp.com/group/project，但希望实际使用 git@gitlab.ipipp.com:group/project.git，可以执行：
git config --global url."git@gitlab.ipipp.com:".insteadOf "https://gitlab.ipipp.com/"
这段配置的含义是，当 Git 遇到以 https://gitlab.ipipp.com/ 开头的 URL 时，自动替换成 git@gitlab.ipipp.com:。Go 工具链在拉取模块时会构造 HTTPS URL 调用 Git，而 Git 在真正连接前应用 insteadOf 规则，从而切换到 SSH。配置完成后，可以用 git ls-remote https://gitlab.ipipp.com/group/project 来验证重写是否生效，如果返回的是 SSH 握手错误或成功列表，说明已生效。
使用 SSH 时，机器上必须存在对应的私钥，并且公钥已添加到私有平台账户或部署密钥中。CI 环境通常通过环境变量写入私钥，再执行 ssh-keyscan 把主机加入 known_hosts，否则首次连接会因主机验证失败而中断。可以在 Dockerfile 或 CI 脚本中加入：
mkdir -p ~/.ssh ssh-keyscan gitlab.ipipp.com >> ~/.ssh/known_hosts
如果需要为不同仓库使用不同密钥，可以借助 SSH config 的 Host 别名，再配合 Git 的 insteadOf 规则实现细粒度控制。例如在 ~/.ssh/config 中定义 Host 为 gitlab-private，然后在 Git 配置中将模块主机指向该别名。这种方式在大规模团队中能够避免所有仓库共用一把密钥带来的权限混乱。
常见私有平台配置实践：GitLab、GitHub 与 Bitbucket
不同平台的仓库路径层级不同，GOPRIVATE 的写法也要相应调整。GitLab 自建实例通常以域名作为前缀，例如 GOPRIVATE=gitlab.ipipp.com。GitHub 则建议精确到组织或用户，例如 GOPRIVATE=github.com/your-org，这样可以避免误伤公共模块。Bitbucket 的路径中可能包含 ~ 或者项目 key，但 GOPRIVATE 只关心路径前缀，因此写 bitbucket.org/your-workspace 即可。
在 GitLab 中，个人访问令牌的创建路径为 Settings 到 Access Tokens，勾选 read_repository 或 read_api 权限。使用 HTTPS 拉取时，.netrc 中的 login 字段填写 oauth2，password 填写令牌。对于 SSH，则把公钥添加到 User Settings 到 SSH Keys。GitLab 的模块拉取还支持 subgroup，GOPRIVATE 只需覆盖到根域名，不需要为每个 subgroup 单独配置。
GitHub 私有仓库使用 HTTPS 时，访问令牌需要具备 repo 权限。由于 GitHub 已停止支持账号密码拉取，必须使用 personal access token 或 fine-grained token。对于 fine-grained token，需要显式授予对应仓库的 Contents 读取权限。Go 模块拉取时，Git 通常会请求 https://github.com/your-org/repo，令牌作为密码填入 .netrc 即可。如果组织启用了 SSO，令牌还需要在组织授权列表中启用。
Bitbucket 的私有模块配置思路类似，GOPRIVATE 设置为 bitbucket.org/workspace，认证可以使用 App password 作为 HTTPS 密码。如果 Bitbucket 的仓库路径包含 ~username，在 module path 中要保留该字符。也可以直接使用 SSH 并配置 insteadOf 重写，灵活度较高。
私有代理与 CI/CD 环境优化
当团队规模变大，直接让每台开发机和 CI 容器访问私有 Git 仓库会带来权限管理和网络策略问题。此时可以引入私有 Go 模块代理，例如 Athens、Goproxy 或 Artifactory 的 Go 仓库。私有代理可以缓存公共模块，也可以代理私有模块，并统一处理认证。开发机只需要配置 GOPROXY 指向私有代理地址，同时设置 GONOPROXY 和 GOPRIVATE 确保私有模块不走公共代理。私有代理本身负责连接私有 Git 平台。
go env -w GOPROXY=https://goproxy.ipipp.com,direct go env -w GOPRIVATE=gitlab.ipipp.com go env -w GONOPROXY=gitlab.ipipp.com
上面的配置中，GOPROXY 包含私有代理地址和 direct 兜底。GONOPROXY 明确告诉 Go 工具链，匹配 gitlab.ipipp.com 的模块不要经过任何代理，直接从源仓库拉取。如果希望私有代理也处理私有模块，则可以移除 GONOPROXY，让私有代理配置与 Git 平台的认证集成。常见的 Athens 支持通过 .netrc 文件或 AWS CodeArtifact 等存储后端来传递凭据。
在 CI/CD 中，建议使用环境变量注入认证信息，而不是修改全局 Git 配置。例如 GitLab CI 可以在项目设置里添加 CI/CD Variables，然后脚本中生成 .netrc 文件。GitHub Actions 则可以用 extra_netrc_lines 或者 actions/checkout 的 token 机制。需要保证 GOPRIVATE 在 CI 环境中同样生效，否则不同机器行为不一致，会造成本地可以拉取但流水线频繁失败的问题。
排错：从报错到定位
私有模块配置过程中，最常遇到的错误是 terminal prompts disabled，这表示 Git 在非交互环境中尝试请求用户名密码，但 Go 工具链禁止交互输入。解决方法就是为当前 URL 提供非交互凭据，比如 .netrc 或凭证助手。可以先执行 GIT_TERMINAL_PROMPT=0 go get -x gitlab.ipipp.com/group/project 来复现并查看详细日志。
另一个高频报错是 reading https://sum.golang.org/lookup/...: 404 Not Found 或 checksum mismatch。这说明模块路径没有匹配到 GOPRIVATE，导致 Go 仍然去公共校验数据库查询。可以执行 go env GOPRIVATE 检查是否包含前缀，并确认模块路径的大小写是否一致。环境变量的改变对已经缓存过的模块可能不生效，需要先执行 go clean -modcache 清理缓存再重试。
如果看到 fatal: could not read Username for 'https://gitlab.ipipp.com': terminal prompts disabled，说明 Git 的凭据来源没有匹配到该主机。检查 .netrc 文件是否放在正确路径，权限是否为 600，以及 machine 行是否与 HTTPS URL 的主机名完全一致。对于带端口的 Git 服务，.netrc 的 machine 字段需要写成 host:port 形式。
如果使用的是 SSH，可能遇到 Host key verification failed，这表示 known_hosts 中缺少目标主机指纹。解决办法是提前执行 ssh-keyscan -H gitlab.ipipp.com >> ~/.ssh/known_hosts。另一个 SSH 相关问题是私钥权限过宽导致被忽略，需执行 chmod 600 ~/.ssh/id_rsa。排查完这些问题后，几乎可以覆盖绝大多数私有模块拉取故障。
