如何通过GOPRIVATE环境变量绕过不稳定的公司代理

goPRIVATE 用于声明私有模块域名白名单，匹配后跳过 GOPROXY 和 GOSUMDB，直接 git clone 或 httpS fetch；需正确配置 glob 模式、环境变量及底层访问（ssh/https/Token/防火墙）。

GOPRIVATE 为什么能跳过代理

Go 在 1.13+ 默认启用模块代理（GOPROXY）和校验和数据库（GOSUMDB），但这两个机制对私有域名一概“不信任”——除非你明确告诉它：哪些域名是自家的，不用走代理、也不用查校验和。这就是 GOPRIVATE 的作用：它不是“绕过代理”的开关，而是“声明私有域”的白名单。一旦某个模块路径匹配 GOPRIVATE 中的模式，Go 就会直接走 git clone（或 HTTPS fetch），跳过 GOPROXY 和 GOSUMDB。

常见错误现象：go get 卡在 “verifying github.com/xxx@v0.1.0: checksum mismatch” 或 “proxy.golang.org refused”；其实不是网络不通，而是 Go 想去公共代理查你公司内网的模块，当然失败。

• GOPRIVATE 值是逗号分隔的 glob 模式，比如 git.corp.example.com,github.com/my-org/*
• 必须包含完整路径前缀，my-org/* 不生效，得写 github.com/my-org/*
• 如果用的是自建 gitlab，且项目在子组里，比如 git.corp.example.com/group/subgroup/repo，那就得写 git.corp.example.com/group/* 或更宽泛的 git.corp.example.com/*
• 注意 shell 转义：在 bash/zsh 里用双引号包裹值，避免 * 被本地 shell 展开

设置 GOPRIVATE 的三种实操方式

别只改当前终端的环境变量——那只会让 go build 临时生效，CI/ide/其他用户还是会失败。要覆盖所有场景，得按优先级顺序设置：

• 全局配置（推荐）：运行 go env -w GOPRIVATE=git.corp.example.com,github.com/my-org/*，Go 会把值写进 ~/.go/env，所有后续命令自动继承
• Shell 配置文件：在 ~/.zshrc 或 ~/.bash_profile 中加 export GOPRIVATE="git.corp.example.com,github.com/my-org/*"，然后 source 它；适合多 Go 版本共存或无法用 go env -w 的旧版本
• CI 场景：在 GitHub Actions / GitLab CI 的 job env 中显式设 GOPRIVATE，不要依赖全局配置，避免和缓存或 runner 环境冲突

注意：如果同时设置了 GOPROXY（比如指向 https://goproxy.cn），GOPRIVATE 仍有效——Go 会先匹配白名单，命中就直连，不命中的才走代理。

为什么加了 GOPRIVATE 还连不上私有仓库

最常被忽略的不是 GOPRIVATE 本身，而是它背后依赖的底层访问能力。Go 直连私有仓库时，用的是 git 命令或 HTTP 客户端，这两条路都可能断：

• Git 协议走 SSH？确保 git.corp.example.com 的 SSH key 已加载到 ssh-agent，且 ~/.ssh/config 里配了正确的 Host 别名和 User
• HTTPS 协议？检查是否需要 token 认证：有些 GitLab/GitHub Enterprise 要求在 URL 里带 token，如 https://token:x-oauth-basic@git.corp.example.com/group/repo；Go 不会自动读取 ~/.netrc，得靠 git config --global url."https://token:x-oauth-basic@git.corp.example.com/".insteadOf "https://git.corp.example.com/"
• 公司防火墙拦截了 git 协议端口（9418）或特定 HTTPS 域名？试下 git ls-remote https://git.corp.example.com/group/repo.git 看是否通
• Go 版本太老（GOPRIVATE 在 1.13 引入，但 1.15 及之前对通配符支持不一致，建议至少用 1.16+

和 GONOPROXY、GONOSUMDB 的关系别搞混

这三个变量经常一起出现，但职责完全不同：

• GOPRIVATE 是总开关：声明哪些模块“算私有”，触发后自动禁用代理和校验和检查
• GONOPROXY 是子集控制：只控制代理行为，不影响 GOSUMDB；即使没设 GOPRIVATE，也能单独用它跳过代理，但校验和仍会报错
• GONOSUMDB 同理：只关校验和，不关代理；单独用它会导致模块从代理下载却跳过校验，有安全风险

所以，只要你的私有模块不在公共索引里，就该用 GOPRIVATE，而不是拆开配两个变量。硬要拆，等于自己给自己埋坑：漏配一个，go get 就失败。

真正复杂的地方在于路径匹配逻辑和公司 Git 基础设施的耦合程度——比如用了多级子域名（repo.team1.corp.example.com）、或模块路径和 URL 路径不一致（module "corp.example.com/mypkg" 但实际托管在 git.corp.example.com/mypkg），这时候 GOPRIVATE 的 glob 就得反复试，不能光看文档抄例子。