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，且仅限符合 v\d+.\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 同路径共存，都可能让整个构建链路静默失败。
