本文永久链接 – https://tonybai.com/2026/07/08/go-private-modules-comprehensive-guide
大家好，我是Tony Bai。
Go 语言的依赖管理从 GOPATH 时代走到 Go Modules，公共依赖的拉取体验已经足够顺滑，但只要涉及“私有模块”，绝大多数团队和个人开发者都会在某个时刻撞上同一堵墙。
具体来说，大概率是下面这几个痛点里的一个或几个：
.netrc、git config、CI 环境变量里都可能藏着一份 token，换一台机器、换一个 CI 平台，就要重新配一遍，稍不注意还容易把明文 token 提交进仓库；go.mod 里写死了 github.com/yourname/xxx，哪天想把仓库从 GitHub 挪到自建 GitLab 或者 Codeberg，所有依赖这个模块的代码都要跟着改 import path；govanityurls + Nginx 又要操心证书续期、单点故障；这篇文章尝试把这件事一次性讲透，分三部分：
每种场景我都会给出对应的落地方案，上面这几个痛点，也会在对应的小节里逐一给出解法，供你按需查阅、按需收藏。
在讨论任何具体场景之前，有必要先把几个容易混淆的环境变量和凭据配置方式讲清楚，因为后面所有场景本质上都是在这个底层机制上做排列组合。
方式一：~/.netrc
这是最传统的方式，git、go 命令本身都会读取这个文件：
machine github.com
login your-username
password ghp_your_personal_access_token
以github.com为例，其中的password你可以在“Developer Settings”的“Personal access tokens”中申请，推荐使用“Fine-grained personal access tokens”，你可以更好地控制token的权限粒度。
方式二：git config 的 insteadOf 重写
更推荐这种方式，因为它可以精确控制到某个域名 / 某个协议，而不是一个笼统的凭据文件：
git config --global url."https://oauth2:${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"
如果你更习惯 SSH 方式（配好 deploy key 之后），可以让 HTTPS 的拉取请求自动重写成 SSH：
git config --global url."ssh://git@github.com/".insteadOf "https://github.com/"
CI 环境里，建议把 token 放进 CI 平台自带的 secret 变量，而不是明文写进仓库里的脚本文件，这是最基本的安全底线。
这是整篇文章最重要的一个知识点，后面所有场景都建立在这个区分之上：
GOPRIVATE：告诉 Go 工具链，哪些 module 路径前缀属于私有模块，遇到这些路径时跳过公共 GOPROXY 和 GOSUMDB，直接走版本控制工具（git）直连拉取。例如：export GOPRIVATE=github.com/yourname/*,go.mycompany.com/*
GOPROXY：控制 module 内容本身怎么拉取、怎么缓存，默认是 https://proxy.golang.org,direct。如果你在公司内部有自己的私有代理（Athens、goproxy/goproxy.cn等），一般会配成类似 https://your-internal-proxy,direct 这样的组合。
GOSUMDB：控制是否要向 sum.golang.org 做校验和验证，私有模块通常需要连同 GOPRIVATE 一起把这一层也关掉，否则公共校验服务器根本没有你私有模块的记录，会导致拉取失败。
GOVCS：Go 1.16 引入的安全限制，控制哪些路径允许用哪种版本控制工具拉取，默认只允许公共托管平台走 git/hg 等，私有域名如果不在白名单里，可能需要显式配置，例如：
export GOVCS=go.mycompany.com:git
简单总结一下这四者的关系：GOPRIVATE 划定“哪些是私有的”，GOPROXY/GOSUMDB 决定“公共部分怎么拉、怎么校验”，GOVCS 决定“私有部分允许用什么工具拉”。
理解了这一层，后面无论是个人场景还是组织场景，本质上都只是在“私有仓库放在哪里”和“import path 要不要自定义”这两个维度上做选择，凭据配置这一层的原理是完全一致的。
这是最简单、成本最低的场景。假设你在 GitHub 上有一个私有仓库 github.com/tonybai/privatemodule，配置如下：
export GOPRIVATE=github.com/tonybai/*
git config --global url."https://oauth2:${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"
go get github.com/tonybai/privatemodule 即可正常工作，go.mod 里的 module path 直接就是 github.com/tonybai/privatemodule，不需要任何额外的“翻译层”。
如果你不满足于 github.com/tonybai/privatemodule 这种带着托管平台印记的 import path，希望换成 example.me/go/privatemodule，或者希望以后即便把仓库从 GitHub 挪到 GitLab、Codeberg，import path 也保持不变，这就需要引入 vanity import URL 机制。
原理很简单：Go 工具链请求 https://example.me/go/privatemodule?go-get=1 时，期望拿到一个包含 go-import meta 标签的 HTML 页面，告诉它真实仓库地址在哪里：
<meta name="go-import" content="example.me/go/privatemodule git https://github.com/tonybai/privatemodule">
按运维成本从低到高，有几种落地方式：
方案一：手写静态 HTML，挂到 GitHub Pages / Cloudflare Pages 上
几乎零成本，只要给每个 module 路径建一个静态页面即可，缺点是每新增一个 module 都要手动加一个页面，仓库多了之后维护起来比较琐碎。
方案二：自己部署 govanityurls
govanityurls 是官方 golang.org/x 下的一个开源工具，读取一份 YAML 映射配置，自动生成对应的 go-import 页面。需要自己找一台机器（哪怕是最便宜的 VPS）跑这个服务，前面配一层 Nginx 做 TLS 终止。可控性最高，但要自己维护这套服务的可用性和证书续期。
方案三：用 gvu 这类托管服务
如果不想自己运维一套 govanityurls + Nginx，也可以用 gvu（gomodvanityurls.com）这类托管化的 vanity URL 服务，一条命令创建映射：
gvu add example.me/go/privatemodule https://github.com/tonybai/privatemodule.git
不需要自己起服务、配证书，适合不想为了一个 vanity 层单独维护基础设施的个人开发者。这只是三种方案里的一种，具体选哪种，取决于你是否愿意为了完全的可控性，多维护一套自己的服务。
如果你更进一步，连代码托管也不想依赖第三方平台，自己在 VPS 上跑了 Gitea、GitLab CE 或者 Codeberg 式的自建 Git Server，这里有个关键认知：vanity 解析层和实际代码托管，完全可以是两个互相独立的服务，用的甚至可以是不同的域名、不同的机器。
这种场景下，前面三种方案依然都成立，只是 go-import 里指向的真实仓库地址，从 github.com/... 换成了你自己 VPS 上的 Git Server 地址，例如：
<meta name="go-import" content="example.me/go/privatemodule git https://git.example.me/tonybai/privatemodule">
对应到 gvu 的用法上，就是把目标仓库地址换成你自建 Git Server 的地址：
gvu add example.me/go/privatemodule https://git.example.me/tonybai/privatemodule.git
同样，手写静态页面或者自建 govanityurls 这两种方式在这个场景下也完全适用，选择哪种取决于你愿意为“完全自主可控”付出多少运维成本。
组织场景相比个人场景，多出的核心考量是：仓库数量更多、参与人员更多、可用性要求更高——vanity 解析服务一旦故障，可能意味着全公司的 CI 流水线都构建失败，这是个人场景基本不需要考虑的风险等级。
这是最常见的组织场景，凭据管理上比个人场景多几个需要注意的点：
其余配置和个人场景完全一致，GOPRIVATE 换成组织域名前缀即可：
export GOPRIVATE=github.com/mycorp/*
这是很多团队迟早会遇到的需求：不希望 go.mod 里到处是 github.com/mycorp/xxx，而是想统一成 go.mycompany.com/xxx，一方面是品牌语义，另一方面是为未来可能的仓库迁移（比如从 GitHub 换到自建 GitLab）留出余地——只要 vanity 层的映射改一下，所有下游使用方的 import path 完全不用变。
五年前我在公司内部第一次搭建这类方案时，写过几篇实践记录（《小厂内部私有Go module拉取方案》、《小厂内部私有Go module拉取方案（续）》和《小厂内部私有Go module拉取方案3》），走的就是自建 govanityurls + Nginx 这条路。这套方案跑了五年，整体稳定，最大的优势是完全自主可控，不依赖任何第三方服务；代价是每新增一个仓库都要手动改一次映射配置、重载一次 Nginx，团队规模大了之后，这个日常维护成本会逐渐显现出来。
如果团队不想自己承担这部分运维成本，用 gvu 这类托管方案可以把“新增映射”这个动作压缩成一条命令，而且天然具备高可用（不用担心自己那台跑 govanityurls 的机器挂了导致全公司构建失败）：
gvu add go.mycompany.com/privatemodule https://github.com/mycorp/privatemodule.git
两种路线各有取舍：
具体选哪个，取决于团队愿意在这件事上投入多少运维精力。
这是组织场景里最复杂、也最容易被低估的一种情况：私有代码托管在内部数据中心自建的 GitLab / Gitea 上，同时又希望有一层语义化的 vanity import path。原理和 前面个人场景自建git server完全一致，只是仓库地址换成了内部数据中心的地址（通常是内网 IP 或内网域名）。
这里额外提一句：如果你的团队还涉及把这类私有代码以“白盒交付”的方式给到外部客户，会遇到一个更棘手的问题——客户的网络环境访问不到你内部的 vanity 服务和内部仓库，这又是另一套需要专门讨论的方案了，我在上一篇《五年，三篇文章，一个我一直没真正解决的问题》里记录过我的具体做法，这里不展开。
把上面讨论的几个维度整理成一份简单的参考：
go get 拉到，不在乎 import path 好不好看：直接用托管平台的私有仓库 + 对应凭据配置即可，不需要引入 vanity 层。govanityurls（仓库多、要求可控）都是合理选择。无论最终选哪条路，先把第一部分那几个环境变量的职责边界搞清楚，后面遇到的大多数报错，基本都能顺着这条线索排查出来。
还在为写 Agent 框架频频死循环、上下文爆炸而束手无策？我的新专栏 《从0 开始构建 Agent Harness》 将带你：
扫描下方二维码，开启从 0 开始构建Agent Harness 的实战之旅。
你的Go技能，是否也卡在了“熟练”到“精通”的瓶颈期？
继《Go语言第一课》后，我的《Go语言进阶课》终于在极客时间与大家见面了！
我的全新极客时间专栏 《Tony Bai·Go语言进阶课》就是为这样的你量身打造！30+讲硬核内容，带你夯实语法认知，提升设计思维，锻造工程实践能力，更有实战项目串讲。
目标只有一个：助你完成从“Go熟练工”到“Go专家”的蜕变！ 现在就加入，让你的Go技能再上一个新台阶！
商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。