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？

  1. 添加 vanity URL 路由：gvu add gomod.io/mylib https://github.com/yourorg/mylib.git
  2. 更新 go.mod：将 module github.com/yourorg/mylib 改为 module gomod.io/mylib
  3. 更新模块内所有内部 import 为新的 vanity 路径
  4. 打一个新版本标签：git tag v0.2.0 && git push --tags
  5. 通知下游使用者更新 import 路径

能否同时保留 github.com/... 和 vanity URL？

不行。Go modules 要求 go.mod 中的 module 指令是唯一的标准路径。同一段代码不能有两个不同的 module path。选择其一并坚持使用。

需要为 /v2、/v3 等主版本单独设置路由吗？

不需要。路由自动支持 Go module 的主版本后缀（/v2、/v3 等），只需添加基础路由即可：

gvu add gomod.io/mylib https://github.com/yourorg/mylib.git

这一条路由即可同时服务 gomod.io/mylib、gomod.io/mylib/v2、gomod.io/mylib/v3 等所有版本。服务端会自动检测版本后缀、剥离后进行路由查找，并在 go-import meta tag 的 prefix 中保留版本号 — 完全符合 Go module 规范。

入门

使用 gomod.io 路由需要注册账户吗？

不需要。当你首次运行 gvu add 命令时，系统会自动创建一个匿名账户。无需邮箱或注册流程。不过匿名账户限制为 5 条路由，且仅限 gomod.io 域名。

如何从 Anonymous 升级为 Verified？

运行 gvu auth bind your@email.com，输入发送到邮箱的验证码即可。升级后你的账户变为 Verified，可使用最多 10 条路由 并解锁自定义域名功能。

GOPRIVATE 是什么？为什么需要设置？

GOPRIVATE 告诉 Go 工具链直接从源端（通过 Git）获取指定的模块路径，而不是从公共 Go 代理（proxy.golang.org）。如果不设置，代理将无法解析你的私有 vanity URL。

export GOPRIVATE=gomod.io
# 如果有自定义域名，也加上：
export GOPRIVATE=gomod.io,go.yourcompany.com

配额与方案

AnonymousVerifiedPro
总路由数51050
自定义域名✗✓✓
域名绑定✗✗✓ (50)
短路径（< 4 字符）✗✗✓

如何订阅 Pro？

运行 gvu subscribe，按交互流程完成支付。付款后管理员会核实你的交易（通常 24 小时内），然后自动升级你的账户。

支持哪些支付方式？

方式适用人群
微信支付中国大陆用户
支付宝中国大陆用户
PayPal海外用户

可选择月付或年付。详见定价。

Pro 订阅过期后路由会怎样？

Pro 过期后，账户降级为 Verified（10 条路由），超出的路由会被冻结。它们不会被立即删除 — 续费订阅即可重新激活。

  • 运行 gvu auth whoami 可查看到期日期和剩余天数
  • 剩余 7 天或更少时会显示警告提示
  • 续费后，所有冻结的路由会自动恢复

注意： 冻结的路由保留 90 天。如果 90 天内未续费，冻结路由将被永久删除。

自定义域名

如何设置自定义域名？

  1. 升级为 Verified：gvu auth bind your@email.com
  2. 创建 CNAME DNS 记录：go.yourcompany.com → gomodvanityurls.com
  3. 等待 DNS 生效（通常几秒到几分钟）
  4. 添加路由：gvu add go.yourcompany.com/mylib https://github.com/yourorg/mylib.git
  5. TLS 证书会通过 Caddy On-Demand TLS 自动配置

详见自定义域名。

自定义域名需要手动配置 HTTPS 吗？

不需要 — TLS 证书全自动管理。CNAME 配置完成后，首次请求时即会自动签发证书。

为什么 gvu add 要求先配置 DNS？

为防止域名劫持，服务端会在创建路由前验证域名的 CNAME 记录。请先配置 CNAME，等待 DNS 生效后，再运行 gvu add。如果 DNS 尚未配置，会收到 DNS_NOT_CONFIGURED 错误。

其他用户可以在我的自定义域名下添加路由吗？

  • Pro 用户：不可以。当你首次在某个自定义域名下添加路由时，该域名会自动绑定到你的账户。其他用户会收到 DOMAIN_ALREADY_BOUND 错误。
  • Verified 用户：可以 — Verified 账户可以使用自定义域名，但不享有独占域名绑定。升级为 Pro 即可锁定你的域名。

如果别人先绑定了我的域名怎么办？

请联系管理员并提供域名所有权证明（如 DNS TXT 记录或域名注册商截图）。验证通过后，我们可以转移绑定。

删除所有路由会释放域名绑定吗？

不会。即使域名下的所有路由都被删除，域名绑定仍然有效。这可以防止意外丢失域名归属。如需释放绑定，请联系管理员。

通配路由

什么是通配路由？

通配路由让你用一条规则覆盖自定义域名前缀下的所有仓库，无需逐个添加。需要 Pro 账户和自定义域名。详见通配路由。

可以在 gomod.io 上使用通配路由吗？

不可以。通配路由仅适用于自定义域名，gomod.io 路由只支持精确匹配。

通配路由会占用配额吗？

会。每条通配路由占 1 个 Pro 配额（共 50 个），与普通路由一致。

通配路由和精确路由同时匹配时怎么处理？

精确路由始终优先。通配路由只在无精确匹配时生效。参见优先级规则。

可以同时使用 Repo 通配和 Subdir 通配吗？

不可以。Repo 通配（W1）和 Subdir 通配（W2）互斥，每条路由只能选一种。

通配规则匹配到的仓库不存在怎么办？

go get 会报 “repository not found” 错误，与精确路由行为一致。通配规则只负责解析 URL，仓库必须存在于 Git 托管平台上。

Pro 过期后通配路由还能用吗？

没有特殊处理 — 通配路由与普通路由一样，Pro 过期后会被冻结和删除。参见 Pro 有效期与续费。

故障排查

go get 报错 “module declares its path as…”

说明你的 go.mod module path 与 vanity URL 不匹配。请将 go.mod 更新为 vanity URL。参见 为什么 go.mod 必须使用 vanity URL？

go get 报错 “no Go modules found”

检查 GOPRIVATE 是否包含了你的 vanity 域名：

go env GOPRIVATE

如果为空或缺少你的域名，设置它：

go env -w GOPRIVATE=gomod.io

gvu list 中路由显示为 “Frozen”

冻结的路由表示你的 Pro 订阅已过期，账户已降级为 Verified（10 条路由），第 11 条起的路由被冻结。运行 gvu subscribe 续费 — Pro 重新激活后，所有冻结的路由会自动恢复。你也可以用 gvu remove 删除多余的路由。冻结路由的保留期为 90 天，超时未续费将被永久移除。

运行 gvu add 时服务器返回 RATE_LIMITED

匿名用户有频率限制以防止滥用。等待几分钟后重试，或绑定邮箱（gvu auth bind）以获得更高的限额。

Windows

运行 gvu.exe 时 Windows 显示"Windows 已保护你的电脑"

这是 Microsoft SmartScreen 安全机制 — 它会标记下载量尚少的新发布程序。绕过方法：

  1. 点击**“更多信息”**
  2. 点击**“仍要运行”**

更好的替代方案（完全避免 SmartScreen 警告）：

# 使用 Scoop 安装（自动配置 PATH，无 SmartScreen 警告）
scoop bucket add gomodvanityurls https://github.com/gomodvanityurls/scoop-bucket
scoop install gvu

# 如果你有 shell 环境（WSL、Git Bash 等），使用 install.sh
curl -fsSL gomodvanityurls.com/install.sh | bash

随着更多用户安装 gvu，SmartScreen 警告会逐渐消失。

Windows 上如何更新 gvu？

通过 Scoop 安装的：

scoop update gvu

通过 install.sh 安装的（WSL/Git Bash）：

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

手动安装的： 从 GitHub Releases 下载最新 .exe 替换旧文件。