5 分钟上手 gvu：把 vanity import path 这件事，从“半天运维”变成一条命

大家好，我是Tony Bai。

上一篇《五年，三篇文章，一个我一直没真正解决的问题》里，我记录了这五年折腾私有 Go module 拉取方案的几段经历，也提到今年白盒交付给客户时踩的新坑。文章结尾我说会把这个工具单独写篇上手文章——今天这篇就是它。

gvu（GomodVanityUrls 的缩写）现在正式开放公测，官网在 gomodvanityurls.com。这篇文章不谈太多背景，直接上手，5 分钟带你走完从安装到拉取用上第一个私有 module 的完整流程。

gvu 是什么

一句话概括：gvu 是一个命令行工具，用来把 Go module 的 vanity import path（比如 mycompany.com/go/common）映射到你真实的代码仓库地址（GitHub / GitLab / Bitbucket / Codeberg / 自建仓库都支持），全程一行命令搞定，不需要你再手写 govanityurls 的 YAML 配置，也不需要自己维护 Nginx。

如果你看过我五年前那几篇搭建私有 Go module 拉取方案的文章，就知道这背后原本要做的事：起一个 govanityurls 服务、写映射配置、配 Nginx 反代、（如果要自定义域名）自己签 TLS 证书。gvu 把这一整套操作压缩成了一行 gvu add。

安装

Linux / macOS

curl -fsSL gomodvanityurls.com/install.sh | bash

Windows

如果你用 Git Bash / MSYS2 / Cygwin/ WSL/ WSL2，直接执行和上面一样的命令即可，脚本会自动识别 Windows 环境并下载对应的 .exe。

如果你在Windows上使用 Scoop 的话，可以在Powershell命令行里执行下面：

scoop bucket add gomodvanityurls https://github.com/gomodvanityurls/scoop-bucket
scoop install gvu

装完之后，跑一下 gvu --version 确认安装成功。

添加你的第一个 vanity URL

最简单的方式是直接用 gvu 提供的默认域名 gomod.io，不需要注册、不需要配 Domain解析，一行命令（以你的私有仓库在github.com上为例）：

$ gvu add gomod.io/private-module https://github.com/yourorg/private-module.git

✔ Route created successfully!
═══════════════════════════════════════════════════════════
┃ Route ID:     m_abc123
┃ Vanity Path:  gomod.io/private-module
┃ Target Repo:  https://github.com/yourorg/private-module.git
┃ Quota:        1 / 5 used
═══════════════════════════════════════════════════════════

这条命令执行时，gvu 会自动帮你创建一个匿名账号（免签名、免邮箱），并且自动识别出这是个 GitHub 仓库。GitLab、Bitbucket、Codeberg 或者你自己内网的 GitLab 也都是同样的用法，把仓库地址换掉即可，gvu 会自动识别托管平台。

如果你的仓库需要用 SSH 方式拉取，也可以直接传 SSH 地址：

gvu add gomod.io/private-module ssh://git@github.com:yourorg/private-module.git

告诉 Go 工具链去哪里解析这个路径

export GOPRIVATE=gomod.io

建议把这行加到你的 ~/.bashrc 或 ~/.zshrc 里，一劳永逸。

在代码里用起来

在你的 go.mod 里，module path 要直接用 vanity path，而不是原始的 Git 托管地址：

// go.mod —— 正确
module gomod.io/private-module

// go.mod —— 错误，会直接去github上拉去私有仓库
module github.com/yourorg/private-module

如果你的模块之前用的是 github.com/... 这样的 module path，迁移时记得把它改成 vanity path 再发布。

改好之后，同组织内有github.com私有仓库访问权限的人 import "gomod.io/private-module" 就能正常拉取了。

Go 工具链会自动把这个 vanity path 解析到你背后真实的仓库地址——以后即便你把代码从 GitHub 挪到自建 GitLab，只要在 gvu 里改一下映射，所有使用方的 import path 完全不用变。这也是五年前我们折腾 govanityurls 时最看重的那个特性，gvu 把它继承了下来，而且不需要你自己运维那套基础设施。

管理你的路由

# 查看所有已注册的路由
gvu list

# 删除一个路由
gvu remove m_abc123

# 批量删除
gvu remove m_abc123 m_def456 -y

如果你的仓库结构更复杂一点

Monorepo 场景：如果一个仓库里有多个 Go module（比如 go/module-a/go.mod），用 --subdir 指定子目录（需要 Go 1.25+）：

gvu add gomod.io/module-a https://github.com/yourorg/monorepo.git --subdir go/module-a

自定义域名场景：如果你不想用 gomod.io 这个默认域名，想用自己或公司的域名（比如 go.mycompany.com）做 vanity path 前缀，需要先升级到 Verified 账号（免费，只需绑定邮箱）并配置好 DNS CNAME。这部分内容稍微多一点，我会放在下一篇有关gvu使用的文章中详细讲，因为这正好对应我们当年真实的迁移场景。

账号与配额

匿名账号（也就是你什么都不注册、直接 gvu add 或gvu auth signup时自动创建的那种）免费可以用 5 个路由，够个人项目和小范围试用。用 gvu auth bind your@email.com 免费升级成 Verified 账号可以拿到 10 个，并解锁自定义域名。如果你需要更大的配额、短路径、自定义域名下的通配路由这类进阶能力，可以看一眼 pricing 页面（https://gomodvanityurls.com/pricing），这篇就不展开了。

大家随时可以用下面这条命令看自己账号的状态：

gvu auth whoami

小结

到这里，你应该已经跑通了从安装到用上第一个私有 module 的完整流程——中间没有 Nginx，没有 YAML，也没有证书要自己签。

这就是 gvu 现在的公测版本。如果你在使用中遇到问题，或者有功能上的想法，欢迎去 Community 页面 ，或使用gvu issue 反馈，我会认真看每一条。

下一篇我会把五年前那套"手动 govanityurls + Nginx"的方案，原样迁移到 gvu 上，一步步对比迁移前后到底省了多少事——这也是很多老读者最关心的问题：如果我已经有一套手搭的方案，值不值得换。