Golang模块语义化版本号规则解析

Go module 版本号必须以 v 开头，是工具链硬编码要求；Git tag、依赖引用和伪版本均需符合此规则，主版本升级须变更模块路径。

Go module 版本号必须以 v 开头

Go 的模块版本解析器严格要求语义化版本号前缀为 v，比如 v1.2.3、v0.1.0。不加 v（如 1.2.3）会被 go get 或 go list 拒绝，报错类似：invalid version: version "1.2.3" does not start with "v"。

这个 v 不是约定俗成的前缀，而是 Go 工具 链硬 编码 识别的标记。它和 Git tag 名称必须完全一致——你发布模块时打的 tag 是 v1.5.0，用户才能用 go get example.com/mymod@v1.5.0 正确拉取。

• Git tag 必须是 vX.Y.Z 格式（支持 v0.Y.Z、v1.Y.Z 及更高主版本）
• go.mod 文件里 module 行不包含版本；版本只体现在 tag 和依赖引用中
• 预发布版本写成 v1.2.3-alpha.1 是合法的，Go 支持完整的 SemVer 2.0 预发布语法

go list -m -versions 显示的是 tag，不是分支或 commit

运行 go list -m -versions example.com/mymod 列出的版本，全部来自该仓库已打的 Git tag，且仅限符合 vd+.d+.d+（或带预发布后缀）格式的 tag。它不会显示 main、dev 这类分支名，也不会把任意 commit hash 当作版本。

常见误解是以为加了 -u 就能升级到最新 commit —— 实际上 go get -u 只会升级到满足当前主版本约束的 ** 最新合法 tag**。比如你依赖的是 v1.2.0，而远程有 v1.2.1 和 v1.3.0，go get -u 会升到 v1.3.0（因主版本仍是 v1），但不会升到 v2.0.0，除非显式改写 go.mod 中的版本引用。

立即学习“go 语言免费学习笔记（深入）”；

• 如果想临时测试未打 tag 的代码，只能用 go get example.com/mymod@commit-hash 或 @branch-name，但这不属于“版本”，go list -m -versions 不会列出它们
• 私有模块若托管在 GitLab/GitHub，需确保 tag 是 public 的（即未被设为 lightweight tag 以外的隐藏状态）

主版本号变更必须换模块路径

Go 不支持同一模块路径下的 v1 和 v2 共存于 go.mod。也就是说，example.com/mymod 的 v1.5.0 和 v2.0.0 不能同时作为依赖被引入——工具链会报错：ambiguous import: found example.com/mymod in multiple modules。

正确做法是：当发布 v2 时，模块路径必须同步更新为 example.com/mymod/v2，并在其 go.mod 第一行写明：module example.com/mymod/v2。这样 v1 和 v2 就是两个独立模块，可共存。

这个规则直接决定你的 API 兼容性承诺是否可信。一旦 v2 路径确立，后续所有 v2.x.y 更新都必须保持向后兼容（按 SemVer 规则）；而 v3 就得再改成 /v3，依此类推。

• 旧版 v0.x.y 和 v1.x.y 之间无需改路径（v0 视为不稳定开发阶段）
• 使用 go mod edit -module 可安全重写模块路径，但需同步更新所有导入语句
• GitHub 上的模块若用 github.com/user/repo，v2 路径就是 github.com/user/repo/v2，不是 github.com/user/repo/v2.0.0

伪版本号（pseudo-version）是怎么生成的

当你用 go get example.com/mymod@master 或 @8f3a1e7 这类非 tag 引用时，Go 会自动生成一个伪版本号，形如：v0.0.0-20230412152834-8f3a1e7b9c0a。它由三部分组成：v0.0.0- + UTC 时间戳 + commit hash 前缀。

这个伪版本号只用于记录依赖快照，不参与语义化比较。它不会出现在 go list -m -versions 输出中，也不能被其他模块当作正式版本引用（别人 go get 你模块时，若你 go.mod 里写了伪版本，他们拉下来的也是同一个 commit，但会生成自己的伪版本号）。

容易忽略的一点是：伪版本号里的 commit hash 是完整 12 位（不是 Git 默认的 7 位），且时间戳精确到秒。如果你看到 v0.0.0-00010101000000-000000000000，说明该模块没有 Git 信息（比如本地 replace 指向一个无 Git 仓库的目录）。

• 用 go mod download -json 可查某个依赖实际解析出的伪版本号
• CI 构建时若依赖伪版本，建议用 go mod verify 确保 checksum 一致
• 发布正式版前务必删掉 go.mod 中所有伪版本，改用真实 tag 引用

版本号表面只是字符串，但在 Go 模块体系里，它绑定了 Git tag、模块路径、工具链解析逻辑和依赖图拓扑规则。漏掉一个 v，或误以为 v2 能和 v1 同路径共存，都可能让整个构建链路静默失败。