v2必须出现在模块路径里，因为Go强制要求主版本≥2的模块通过/v2等后缀实现路径隔离，使github.com/foo/bar与github.com/foo/bar/v2成为完全独立的模块，否则go get或import会失败。
为什么 v2 必须出现在模块路径里
Go 要求主版本号 ≥2 的模块，其模块路径必须显式包含 /v2、/v3 等后缀，不是可选，而是强制。这是因为 Go 用路径区分不兼容的主版本——github.com/foo/bar 和 github.com/foo/bar/v2 是两个完全独立的模块，各自有独立的 go.mod、依赖树和导入路径。
常见错误现象：go get github.com/foo/bar@v2.0.0 报错 unknown revision v2.0.0 或导入失败，本质是模块未声明 /v2 后缀，导致 Go 认为它仍是 v1 模块，拒绝解析 v2 标签。
- 模块发布 v2 时，必须先改
go.mod中的module行：从module github.com/foo/bar改为module github.com/foo/bar/v2 - 所有内部包的导入路径也要同步更新，比如
github.com/foo/bar/pkg→github.com/foo/bar/v2/pkg - 旧代码若仍要引用 v1，保持原路径；新代码用新路径，二者可共存
go.mod 里写错主版本后缀的典型后果
后缀写法错一个字符就会让整个模块无法被正确识别或构建。最常踩的坑是把 /v2 写成 v2（缺斜杠）、/V2（大小写）、//v2（双斜杠）或 /v2.0.0（带次修订号）。
实际表现：运行 go build 或 go list -m all 时，该模块可能显示为 github.com/foo/bar/v2 v0.0.0-00010101000000-000000000000（伪版本），而非你打的 v2.0.0 标签；或者 import 语句报 cannot find module。
立即学习“go语言免费学习笔记（深入）”；
- 确认方式：执行
go mod edit -json查看Module.Path字段是否严格匹配 Git 仓库根路径 +/vN - Git 标签必须与模块路径一致：若
go.mod是github.com/foo/bar/v2，标签就得是v2.0.0，不能是v2或2.0.0 - gopkg.in 是例外：它要求
.v2（点开头），如gopkg.in/yaml.v2，路径中无斜杠
如何安全升级到 v2 并兼容老用户
升级不是改个路径就完事，关键在于让老项目不崩、新项目能用、CI 不挂。核心原则是：v1 和 v2 是两个平行模块，不能“覆盖”，只能“并存”。
使用场景：你维护一个被数百个项目依赖的库，其中有些还在用 v1，有些想试 v2 新特性。你不能删掉 v1 的 tag，也不能让 v2 的改动破坏 v1 的构建。
- 在 Git 仓库中，v1 分支/标签保持不动；v2 从新 commit 开始，基于新
go.mod路径开发 - 发布前，确保 v2 的
go.mod中require块不意外拉入 v1 的同名模块（避免循环或冲突） - 文档里明确写清：老用户继续
import "github.com/foo/bar"；新用户用import "github.com/foo/bar/v2" - CI 中建议同时跑 v1 和 v2 的测试，尤其检查
go mod verify是否通过
为什么 v0 和 v1 不需要后缀
Go 规定 v0.x.y 是开发中版本，无兼容性承诺；v1.x.y 是首个稳定版本，隐含“向后兼容”的契约，但路径仍沿用无后缀形式。这是为了降低初版门槛，也避免大量现有 v1 项目被迫改导入路径。
容易被忽略的细节：一旦你发布了 v1.0.0，后续所有 v1.x.y 升级都必须保持 API 兼容——哪怕只加一个导出函数，也得是 v1.1.0，不能跳 v2；否则就必须切到 /v2 路径，且老用户代码不受影响。
-
v0.0.0-开头的伪版本（如v0.0.0-20260805123456-abcdef123456）只用于未打 tag 的开发分支，不可用于正式发布 - 如果你的模块长期停留在
v0，说明它还没准备好承诺兼容性；上线前务必打v1.0.0标签并固定路径 - 主版本号变更永远只由 API 不兼容改动触发，和功能多寡无关
