Go模块版本号必须以v开头，是Go工具链硬编码规则而非风格约定；不加v（如1.2.3）将直接报invalid version错误，git tag和引用必须严格一致，主版本≥2时module路径和import语句均需含/v2后缀。
Go模块版本号必须以v开头，不是风格问题，是硬编码规则
不加v的 tag（比如1.2.3）会被 Go 工具链直接拒绝，报错类似：invalid version: version "1.2.3" does not start with "v"。这不是警告，是解析失败——go get、go list -m -versions全都不认。
Git tag 名必须和引用时完全一致：你打的是v1.2.3，用户才能写go get example.com/pkg@v1.2.3。用git tag 1.2.3或git tag v1.2.3-rc1（漏点或大小写混用）都会导致依赖拉不到。
-
v1.2.3✅ 合法 -
1.2.3❌ 解析失败 -
v1.2.x❌ 非数字段不被接受 -
v1.0.0-alpha.1✅ 支持完整预发布语法 -
v1.0.0+2023⚠️ 构建元数据（+后内容）被 Go 完全忽略，不参与比较
主版本≥2时，module路径和import语句必须带/v2后缀
Go 不允许同一路径下共存 v1 和 v2。如果你只改了 tag 为v2.0.0，但没动 go.mod 里的 module 行，go get 会报：unknown revision v2.0.0 或 invalid version: version "v2.0.0" does not match module path。
必须同步改两处：
立即学习“go语言免费学习笔记（深入）”；
-
go.mod第一行改成：module github.com/you/repo/v2 - 所有
import语句改成：import "github.com/you/repo/v2"
漏掉任一环节，编译直接失败：cannot load github.com/you/repo: module github.com/you/repo@latest found (v2.1.0+incompatible) —— 这个 +incompatible 就是警示：路径没对上，Go 强制降级为“不兼容模式”加载，行为不可控。
@latest 不跨主版本，且可能在 CI 中悄悄改变构建结果
go get example.com/pkg@latest 实际取的是当前主版本下最新稳定版（比如 v1.12.3），绝不会升到 v2.x，哪怕远程已有 v2.0.0。它只在 v1.* 范围内找最大版本。
但风险在于：@latest 每次执行都可能拉到新发布的 v1.12.4，导致本地和 CI 构建结果不一致。生产环境应避免。
- 锁定精确版本：
go get example.com/pkg@v1.9.0→go.mod写死require example.com/pkg v1.9.0 - 升级时明确指定：
go get example.com/pkg@v1.10.0，而不是依赖@latest碰运气 - 验证最终选中版本：
go list -m all | grep pkg
go mod tidy 选的是“最小语义版本”，不是“最新版”
Go 用 MVS（最小版本选择）算法，找满足所有依赖约束的**语义序最小版本**。这常让人困惑：为什么升级一个依赖反而让另一个降级？
例如：
- A 依赖
log v1.10.0 - B 依赖
log v1.8.0 - C 依赖
log v1.2.0
MVS 选 v1.10.0（因为 v1.8.0 和 v1.2.0 都不满足 A 的最低要求）。但如果 A 改成 v1.12.0，而 B 仍锁在 v1.8.0，go mod tidy 反而可能把整个项目升到 v1.12.0 —— 因为这是唯一同时满足 A（≥1.12.0）和 B（≥1.8.0）的最小版本。
真正容易被忽略的点是：版本号本身不决定“新旧”，而是语义序（v1.12.0 > v1.8.0），且预发布版（v1.0.0-beta.1）永远比正式版（v1.0.0）小，即使时间更晚。
