Golang从1.11版本引入Go Modules之后，依赖管理变得规范了很多，但一旦依赖来自公司内网的私有仓库，事情就开始变得麻烦。典型症状是执行go get时先去proxy.golang.org查找模块，查不到就报404，或者即使模块存在也因为无法通过校验和验证而失败。这些问题的根源在于Go默认会把所有依赖都经过公共代理和校验数据库，而私有仓库显然不应该走这条链路。要解决它，核心就是正确配置GOPRIVATE环境变量，并处理好Git的认证方式。
先弄懂GOPRIVATE和相关环境变量的作用
很多文章一上来就教你设置GOPRIVATE，但不解释它到底干了什么，结果换一个场景又不会用了。实际上，GOPRIVATE是一个匹配模式列表，用来告诉Go工具链哪些模块路径属于私有模块。凡是被它匹配到的模块路径，Go会做两件事：第一，不经过公共代理（GOPROXY）直接从源地址下载；第二，跳过公共校验数据库（GOSUMDB）的哈希校验。
它的语法和path.Match一致，多个模式用逗号分隔。比如公司内网的Git服务器域名是git.mycompany.com，那么可以这样设置：
go env -w GOPRIVATE="git.mycompany.com/*" # 如果有多个私有域名，用逗号连接 go env -w GOPRIVATE="git.mycompany.com/*,gitee.internal/*"
这里有个容易踩的坑：模式必须能覆盖到模块的完整路径。如果仓库地址是git.mycompany.com/team/project，那么git.mycompany.com/*可以匹配，但只写git.mycompany.com（不带斜杠和星号）就匹配不到子路径。另外要注意GOPRIVATE是GONOPROXY和GONOSUMDB的默认值来源，如果你只设置了GONOSUMDB而没设置GOPRIVATE，下载仍然会走代理，结果还是失败。
三个变量的关系可以简单概括：GOPRIVATE是总开关，GONOPROXY控制哪些模块不走代理，GONOSUMDB控制哪些模块不做校验。日常开发中直接配GOPRIVATE就够了，除非你需要“走代理但不校验”这种特殊场景才需要单独调后两个。
配置Git让go get能通过私有仓库认证
设置完GOPRIVATE后，Go会尝试直接从源仓库拉代码，但认证这一关还得靠Git自己解决。目前主流的做法有两种：SSH方式和HTTPS方式。
SSH方式比较省心，把公钥部署到Git服务器后基本一劳永逸。但Go默认会用HTTPS协议访问仓库，所以需要告诉Git把对应的HTTPS地址重写成SSH地址。假设私有服务器是git.mycompany.com，配置如下：
git config --global url."git@git.mycompany.com:".insteadOf "https://git.mycompany.com/" # 验证配置是否生效 git ls-remote https://git.mycompany.com/team/project.git
如果第二条命令能正常返回分支列表，说明重写成功，go get就能顺利拉取了。这个方案在Linux和macOS上非常顺滑，但在Windows上要注意SSH密钥的加载问题，建议用git bash执行ssh -T git@git.mycompany.com先验证连通性。
HTTPS方式则适合不方便管理SSH密钥的环境，比如CI构建机器。核心思路是让Git使用存储的凭证或者凭证助手。最直接的做法是把用户名和token写进全局配置：
git config --global url."https://oauth2:你的Token@git.mycompany.com/".insteadOf "https://git.mycompany.com/" # 或者使用系统的凭证管理器（Windows下推荐） git config --global credential.helper manager
第一种方式虽然简单，但Token会明文存在.gitconfig里，安全性要自己权衡。团队协作中更推荐用各自平台的访问令牌配合凭证管理器，Windows用manager，macOS可以用osxkeychain，Linux下用libsecret或者直接依赖CI环境注入的环境变量。
还有一个不太推荐的捷径是给go get加-insecure参数（新版本已标记废弃），它会跳过证书校验，如果内网Git用的是自签名证书，正确做法是把CA证书加入系统信任列表，或者设置Git_SSL_CAInfo指向证书文件，而不是关闭安全检查。
团队协作与CI环境下的统一配置实践
单机配置好之后，更大的挑战是如何让整个团队和CI流水线保持一致。每个人的GOPRIVATE写法不同、认证方式不同，新人入职时往往要折腾半天。这里给出几点实践建议。
首先是把环境配置固化到文档和脚本里。可以在项目仓库放一个bootstrap脚本，内容大致是：
#!/bin/bash # 统一配置Go私有模块环境 go env -w GOPRIVATE="git.mycompany.com/*" git config --global url."git@git.mycompany.com:".insteadOf "https://git.mycompany.com/" echo "私有模块环境配置完成"
其次，CI环境下要区分处理。以GitLab CI为例，官方的golang镜像支持通过变量控制，常见的做法是在流水线里同时设置GOPRIVATE和CI_JOB_TOKEN相关的Git配置：
variables:
GOPRIVATE: "git.mycompany.com/*"
before_script:
- git config --global url."https://oauth2:${CI_JOB_TOKEN}@git.mycompany.com/".insteadOf "https://git.mycompany.com/"这样构建任务会自动使用流水线令牌拉取私有依赖，不需要在CI机器上手工部署密钥。GitHub Actions下思路类似，用secrets存储PAT令牌再注入Git配置即可。
最后提醒两个排查技巧。当拉取仍然失败时，可以用go env GOPRIVATE确认变量是否生效，用GODEBUG=http2client=0 go get -x 模块路径查看详细的下载过程，输出里会明确显示请求走了代理还是直连、Git命令是怎么执行的，定位问题非常高效。另外go mod verify可以帮你确认本地缓存的模块是否完整可信。把GOPRIVATE、Git重写、CI凭证这三件事配齐，Golang私有模块的管理就基本不会有坑了。
Golang私有模块私有仓库GOPRIVATE修改时间：2026-09-10 21:56:40