文档

安装 Linux & macOS curl -fsSL gomodvanityurls.com/install.sh | bash 也可以从 最新版本 下载二进制文件。 Windows 根据你的 shell 环境选择安装方式： 方式 A — PowerShell（推荐）： powershell -ExecutionPolicy ByPass -c "irm https://gomodvanityurls.com/install.ps1 | iex" 脚本会自动检测架构、验证下载完整性并配置 PATH。 运行 gvu --version 验证安装。 方式 B — Git Bash / MSYS2 / Cygwin： 打开你的 shell 终端，然后运行： curl -fsSL gomodvanityurls.com/install.sh | bash 脚本会自动检测 Windows 环境并下载正确的 .exe 二进制文件。 方式 C — WSL/WSL2： 打开 WSL 终端，然后运行： curl -fsSL gomodvanityurls.com/install.sh | bash 方式 D — Scoop： ...

Verified 和 Pro 用户可以使用自己的域名作为 vanity URL 前缀。 前提条件 Verified 或 Pro 账户（运行 gvu auth bind <email> 即可升级） 一个你拥有 DNS 管理权限的域名 已安装 gvu CLI — 参见 快速开始 配置步骤 重要：DNS 必须在运行 gvu add 之前配置好。服务端会在路由创建时验证域名的 CNAME 记录。 1. 配置 DNS 通过 CNAME 将你的域名指向服务： go.yourcompany.com CNAME gomodvanityurls.com 2. 等待 DNS 生效 DNS 变更通常在几秒到几分钟内生效。你可以用以下命令验证： dig go.yourcompany.com CNAME +short # 预期输出：gomodvanityurls.com. 3. 添加自定义域名路由 gvu add go.yourcompany.com/private-module https://github.com/yourorg/private-module.git 服务端会验证 CNAME 记录。如果 DNS 尚未生效，会收到 DNS_NOT_CONFIGURED 错误 — 等待传播后重试即可。 ...

路由管理 命令 说明 gvu add <vanity-path> <repo-url> 添加新的 vanity URL 路由 gvu list 列出所有已注册的路由 gvu remove <route-id> [...] 删除一个或多个路由 gvu add 托管平台会根据仓库 URL 自动识别。 参数 参数 说明 --subdir <path> 仓库中 go.mod 所在的子目录路径（Go 1.25+）。使用 * 表示 subdir 通配（仅 Pro）。单模块仓库无需指定。 示例 # ── gomod.io 路由（默认域名，所有用户可用）── # GitHub gvu add gomod.io/mylib https://github.com/myorg/mylib.git gvu add gomod.io/mylib ssh://git@github.com:myorg/mylib.git # GitLab gvu add gomod.io/mylib https://gitlab.com/myorg/mylib.git gvu add gomod.io/mylib ssh://git@gitlab.com:myorg/mylib.git # Bitbucket gvu add gomod.io/mylib https://user@bitbucket.org/myorg/mylib.git gvu add gomod.io/mylib ssh://git@bitbucket.org:myorg/mylib.git # Codeberg gvu add gomod.io/mylib https://codeberg.org/myorg/mylib.git gvu add gomod.io/mylib ssh://git@codeberg.org:myorg/mylib.git # 自托管 GitLab（自定义端口） gvu add gomod.io/mylib http://gitlab.example.com/group/mylib.git gvu add gomod.io/mylib ssh://git@gitlab.example.com:2222/group/mylib.git # ── Monorepo（Go 1.25+，--subdir）── # go.mod 位于仓库内的 go/module-a/go.mod gvu add gomod.io/module-a https://github.com/myorg/monorepo.git --subdir go/module-a gvu add gomod.io/module-b https://github.com/myorg/monorepo.git --subdir go/module-b # ── 自定义域名路由（仅 Verified/Pro 用户可用）── gvu add go.mycompany.com/mylib https://github.com/myorg/mylib.git gvu add go.mycompany.com/mylib ssh://git@gitlab.com:myorg/mylib.git # ── 通配路由（仅 Pro + 自定义域名）── # Repo 通配 — 覆盖 GitHub org 下的所有仓库 gvu add 'go.mycorp.com/dept1/*' 'https://github.com/dept1/*.git' # Subdir 通配 — 覆盖 monorepo 中的所有子目录 gvu add go.mycorp.com/dept1/mono https://github.com/dept1/mono.git '--subdir=*' 注意： 通配路由需要 Pro 账户和自定义域名。Repo 通配和 Subdir 通配互斥。详见通配路由。 ...

Module Path 为什么 go.mod 必须使用 vanity URL 而不是 github.com/...？ 当你设置了 vanity URL（如 gomod.io/mylib）后，Go 工具链会使用导入路径（即 vanity URL）来定位模块。go.mod 中的 module 指令必须完全匹配： // go.mod — 正确 module gomod.io/mylib // go.mod — 错误 module github.com/yourorg/mylib 如果不匹配，go get 和 go build 会报错： go: gomod.io/mylib@v0.1.0: parsing go.mod: module declares its path as: github.com/yourorg/mylib but was required as: gomod.io/mylib 如何将现有模块迁移到 vanity URL？ 添加 vanity URL 路由：gvu add gomod.io/mylib https://github.com/yourorg/mylib.git 更新 go.mod：将 module github.com/yourorg/mylib 改为 module gomod.io/mylib 更新模块内所有内部 import 为新的 vanity 路径 打一个新版本标签：git tag v0.2.0 && git push --tags 通知下游使用者更新 import 路径 能否同时保留 github.com/... 和 vanity URL？ 不行。Go modules 要求 go.mod 中的 module 指令是唯一的标准路径。同一段代码不能有两个不同的 module path。选择其一并坚持使用。 ...

通配路由让你用一条规则覆盖自定义域名前缀下的所有仓库，无需逐个注册。 前提条件 Pro 账户（运行 gvu subscribe 升级） 已配置 DNS CNAME 的自定义域名 已安装 gvu CLI — 参见 快速开始 注意： 通配路由不支持默认的 gomod.io 域名，仅适用于自定义域名。 Repo 通配（W1） 适用于同一 GitHub 组织或同一路径前缀下有多个仓库的场景。 语法 gvu add '<域名>/<前缀>/*' 'https://<主机>/<组织>/*.git' Shell 引号：* 在 shell 中必须用引号包裹以防止 glob 展开。对包含 * 的参数使用单引号（'...'）。 vanity path 中的 * 匹配任意单个路径段。repo URL 中的 * 会被匹配到的路径段替换。 示例 # 覆盖 go.mycorp.com/dept1/ 下的所有仓库 gvu add 'go.mycorp.com/dept1/*' 'https://github.com/dept1/*.git' 创建此规则后，go.mycorp.com/dept1/ 下的任何 go get 请求都会自动解析： import "go.mycorp.com/dept1/auth" // → github.com/dept1/auth import "go.mycorp.com/dept1/config" // → github.com/dept1/config import "go.mycorp.com/dept1/utils" // → github.com/dept1/utils 无需逐个添加路由 — 新仓库立即生效。 ...