本文永久链接 – https://tonybai.com/2026/07/08/migrate-from-govanityurls-to-gvu
大家好，我是Tony Bai。
上一篇《5 分钟上手 gvu》带大家跑通了一个全新项目从 0 到 1 接入 gvu 的过程。
但对于已经在生产环境跑了好几年 govanityurls 或其他私有Go模块拉取方案的团队（比如五年前的我们自己），更现实的问题是：已有的这套方案，要不要迁、怎么迁。
这篇文章就是要把这件事儿讲清楚，并且给出我们团队真实迁移的完整记录。
这是我在写这篇文章之前，觉得最有必要单独拎出来讲的一点，因为这个误解我自己五年前也有过。
go get、go mod tidy 背后其实有两层完全不同的机制在起作用：
govanityurls / gvu 解决的问题）当你执行 go get mycompany.com/go/common 时，Go 工具链第一步要做的是搞清楚这个 import path 背后到底是哪个仓库、用什么版本控制系统。
它会去请求 https://mycompany.com/go/common?go-get=1，期待拿到一个包含 go-import meta 标签的 HTML 页面，告诉它"真正的仓库在这里"。
govanityurls 和 gvu 干的就是这一件事—— 提供这个"翻译层"，把好看的、语义化的 import path 映射到真实仓库地址。它本身不存代码，不存版本，不存访问私有仓库的凭据，只是一次 HTTP 重定向式的元信息响应。
搞清楚真实仓库地址之后，Go 工具链还需要实际拉取这个 module 的具体版本内容（代码、go.sum 校验信息）。
这一层默认走的是 proxy.golang.org，也可以是你自己搭的私有代理（Athens、GoProxy.io 私有化版本等），负责缓存、加速、以及对私有仓库做鉴权拉取。
两者的关系是：
vanity URL 解析发生在前，GOPROXY 拉取发生在后，一前一后，缺一不可，但解决的是完全不同的问题。
迁移到 gvu 之后，你的私有 module 依然需要一个 GOPROXY（或者用 GOPRIVATE/GONOSUMCHECK 让 Go 工具链直接绕过公共代理走直连）——gvu 只是替你省掉了手动维护 vanity 映射这一层，它不会、也不打算替代你现有的 GOPROXY。
五年前那几篇文章里，我们的架构其实一直是"govanityurls（第一层）+ 内部 GOPROXY（第二层）“的组合，这次迁移改动的只是第一层。
回顾一下五年积累下来的这套东西，大致是这样：
govanityurls 进程，读取一份手写的 vanity.yml，每新增一个私有仓库就要手动加一条映射govanityurls 的端口这套东西五年里总体稳定，但"新增一个仓库 = 改配置 + 重载 govanityurls"这个流程，一直是团队里被吐槽最多的一环，也是这次迁移最想解决的核心痛点。
把所有存量映射列出来。我们当时 vanity.yml 大概是这样的结构（简化版）：
paths:
go/common:
repo: https://internal-git.mycompany.com/go/common
vcs: git
go/authsdk:
repo: https://internal-git.mycompany.com/go/authsdk
vcs: git
# ... 还有几十条
这一步的目的很简单：确认清楚现存映射一共有多少条，后面要在 gvu 里一一重建，同时顺手看一眼这些仓库的命名规律——这会决定下一步走哪条路径。
盘点完存量映射之后，我们发现几十条里大多都遵循同一个规律：仓库地址都是 https://internal-git.mycompany.com/go/<repo>，vanity path 也都是 mycompany.com/go/<repo>，只有仓库名不同。这种情况正好是 gvu 新上线的 wildcard routing（通配符路由）想解决的场景。
不过用之前要先说明两个前提：
gvu subscribe 升级；gomod.io 不支持。也就是说，如果你打算用这个能力，第四步"配置自定义域名"要提到这一步之前先做完。确认这两个前提之后，wildcard routing 分两种：
repo wildcard（覆盖同一个组织 / 路径前缀下的多个仓库）
gvu add 'go.mycompany.com/go/*' 'https://internal-git.mycompany.com/go/*.git'
注意命令里的单引号不是可有可无的——* 在 shell 里会被当成通配符展开，必须用单引号把带 * 的参数包起来，避免被 shell 提前解释掉。这条规则建立之后，go.mycompany.com/go/ 前缀下的任意仓库都会自动解析，不需要逐条添加：
import "go.mycompany.com/go/common" // → internal-git.mycompany.com/go/common
import "go.mycompany.com/go/authsdk" // → internal-git.mycompany.com/go/authsdk
以后团队新开一个仓库，只要命名遵循这个规律，直接就能用，不需要再执行任何 gvu add。
subdir wildcard（覆盖 monorepo 里的多个子模块）
如果你的私有代码是放在一个 monorepo 里、每个子目录一个独立 Go module（需要 Go 1.25+），可以用另一种通配符：
gvu add go.mycompany.com/go/mono https://internal-git.mycompany.com/go/mono.git '--subdir=*'
--subdir=* 里的 * 会被请求路径里对应的子目录名替换，一条规则覆盖 monorepo 里所有子模块，同样不需要逐条声明。
两种通配符不能混用：一条路由要么是 repo wildcard，要么是 subdir wildcard，二选一；而且仓库 URL 里只允许出现一个 *。
剩下命名不规律的几条，用 exact route 单独声明，并且优先级更高。
我们盘点出来的几十条里，有一条是历史遗留的老库，仓库地址和其余的不在一个路径下，这种直接用普通的精确路由声明即可：
gvu add go.mycompany.com/go/legacy https://internal-git.mycompany.com/legacy-repo/oldname.git
gvu 的路由匹配优先级是"精确匹配 > subdir wildcard > repo wildcard”，也就是说，即便这条 legacy 恰好也落在前面那条 repo wildcard 规则的覆盖范围内，精确路由也会优先生效，不用担心两条规则打架。
如果你的仓库命名不规整，或者分散在不同 Git 服务器 / 不同组织路径下，没办法用一条通配符规则覆盖，那就还是老老实实逐条添加：
gvu add gomod.io/common https://internal-git.mycompany.com/go/common
gvu add gomod.io/authsdk https://internal-git.mycompany.com/go/authsdk
值得一提的是配额规则：一条 wildcard 路由，不管它实际覆盖了多少个仓库，只占用 Pro 账号配额里的 1 个路由名额（Pro 账号总配额 50 条）。也就是说，前面那条覆盖了十个仓库的 repo wildcard 规则，只算 1 条，这也是这次迁移里省下配额最明显的一处。
如果你不想让 go.mod 里的 module path 从 mycompany.com/go/common 变成 gomod.io/common（多数团队会希望保留自己的域名语义），或者像上一步那样打算用 wildcard routing，都需要先走自定义域名这条路：
gvu auth bind your@email.com），这一步是免费的，解锁自定义域名能力go.mycompany.com 加一条指向 gvu 的 CNAME 记录gvu subscribe 升级到 Pro 账号（自定义域名本身免费账号就能用，但 wildcard routing 是 Pro 专属能力）这一步本质上是把原来 Nginx 承担的"域名 + TLS"职责，转交给了 gvu。证书签发、续期这些事情，也就不用自己操心了。
找几个存量项目，重新跑一遍 go mod tidy / go build，确认能正常解析到内部仓库。用了 wildcard routing 的话，记得确认一下 GOPRIVATE 里包含的是整个自定义域名前缀，而不是某一个具体仓库路径：
go env -w GOPRIVATE=go.mycompany.com
否则会出现"路由规则本身没问题，但个别 sub-package 解析不出来"这种容易让人摸不着头脑的情况。
另外建议多挑几个不同仓库名分别验证，而不是测一个就当全部通过——尤其是 repo wildcard，如果某个仓库名在目标 Git 服务器上其实不存在，go get 会报"repository not found"，这种情况下用 git ls-remote 把 * 换成实际仓库名单独测一下就能定位。
确认所有存量 module 都迁移验证完毕之后，就可以把 govanityurls 进程和对应的 Nginx 配置下线了。注意，这里下线的只是"第一层"，你的内部 GOPROXY（第二层）该怎么跑还怎么跑，不要连它一起下线。
| 迁移前（手动 govanityurls + Nginx） | 迁移后（gvu） | |
|---|---|---|
| 需要自己运维的组件 | govanityurls 进程、Nginx、TLS 证书 |
0 |
| 新增一个私有仓库的操作 | 改 vanity.yml → 重载 Nginx |
命名规整的一批仓库：新增仓库时不需要任何操作；命名不规律的：一条 gvu add |
| 覆盖 10 个命名规整仓库所需的路由数 | 10 条 vanity.yml 条目 |
1 条 repo wildcard 规则，只占 1 个配额名额（需要 Pro 账号 + 自定义域名） |
| 域名迁移代价（仓库从一个平台挪到另一个平台） | 改 vanity.yml 对应条目，无需下游改动 |
gvu 里改一下映射，无需下游改动（两者在这一点上其实是一样的，这是 vanity URL 机制本身的优势，不是 gvu 独有） |
| TLS 证书 | 自己签、自己续期 | gvu 托管 |
| GOPROXY（module 拉取层） | 不变 | 不变，依然需要 |
最后一行故意留在这里，是想再强调一次：这次迁移动的只是"翻译层"，“拉取层"从头到尾没有变过，这也是我在文章开头要先把两者区分清楚的原因——如果团队里有人指望"上了 gvu 就不用管 GOPROXY 了”，迁移过程中大概率会踩这个认知上的坑。
这次迁移前后花了不到半个小时，大部分时间花在盘点存量映射上，实际的重建操作本身很快——尤其是这次用上了 wildcard routing 之后，原本要逐条敲的十几条 gvu add，命名规整的十条合并成了一条 repo wildcard 规则就解决了，剩下一条历史遗留的老库单独用精确路由声明，优先级还能保证不会被 wildcard 规则误覆盖。
需要提醒一句：wildcard routing 是 Pro 账号才有的能力，而且必须搭配自定义域名使用，如果你的团队规模不大、存量仓库也没几个，逐条 gvu add 完全够用，不必为了这个能力专门升级付费账号——这个功能真正划算的场景，是仓库数量比较多、且命名规律统一的团队。
更重要的是想清楚了一件事：私有 module 拉取这件事，从来不是一个单一问题，而是"vanity 解析"和"内容拉取"两层问题叠在一起。gvu 解决的是前一层，这一层解决好之后，剩下的路由和证书维护成本基本归零。
下一篇，我会回到起源那篇文章埋的那个坑——白盒交付给客户时，怎么用 gvu 在客户组织内部 10 分钟重建一套私有 module 拉取方案。
还在为写 Agent 框架频频死循环、上下文爆炸而束手无策？我的新专栏 《从0 开始构建 Agent Harness》 将带你：
扫描下方二维码，开启从 0 开始构建Agent Harness 的实战之旅。
你的Go技能，是否也卡在了“熟练”到“精通”的瓶颈期？
继《Go语言第一课》后，我的《Go语言进阶课》终于在极客时间与大家见面了！
我的全新极客时间专栏 《Tony Bai·Go语言进阶课》就是为这样的你量身打造！30+讲硬核内容，带你夯实语法认知，提升设计思维，锻造工程实践能力，更有实战项目串讲。
目标只有一个：助你完成从“Go熟练工”到“Go专家”的蜕变！ 现在就加入，让你的Go技能再上一个新台阶！
商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。