/v2 必须出现在 import 路径里，因为 Go 强制要求主版本升级时模块路径同步变更，如 v1→v2 需将 github.com/user/lib 改为 github.com/user/lib/v2，否则编译报错或静默降级。
为什么 /v2 必须出现在 import 路径里
Go 不允许同一模块不同主版本共存于同一 import 路径下。当你升级依赖到 v2.0.0，而它的模块路径仍是 github.com/user/lib，Go 工具链会拒绝解析——因为这违反语义化版本隔离原则。强制要求路径带 /v2（如 github.com/user/lib/v2）是 Go 编译器级的硬性约定，不是可选配置。
常见错误现象：go get github.com/user/lib@v2.1.0 后，import "github.com/user/lib" 仍指向 v1；或者编译报错 cannot find module providing package github.com/user/lib，本质就是没在 import 语句里补上 /v2。
- 主版本变更必须同步改模块路径：v1 → v2 就得从
module github.com/user/lib改成module github.com/user/lib/v2 -
go.mod里的require行也必须匹配：写github.com/user/lib/v2 v2.1.0，不能漏掉/v2 - 调用方代码里所有
import语句都要显式带上/v2，否则 Go 不认这是同一个模块的新主版本
go get 拉取 v2+ 依赖时容易忽略的参数
go get 默认只认不带 /vN 的路径，直接 go get github.com/user/lib@v2.1.0 会失败或静默降级到 v1。必须明确指定带版本后缀的模块路径。
- 正确写法：
go get github.com/user/lib/v2@v2.1.0—— 注意/v2在@前面 - 如果本地已有 v1，且想升级整个项目到 v2，先删掉旧 require 行，再跑
go get github.com/user/lib/v2@v2.1.0，最后go mod tidy - 别依赖
go get -u自动升主版本：它只会升MINOR和PATCH，MAJOR变更必须手动介入
伪版本（v0.0.0-...）能不能跳过 /vN 规则
不能。伪版本只是未打 Git tag 时的临时版本标识，它依然绑定在某个主版本路径下。比如你 go get github.com/user/lib/v2@9a3f2c1，生成的伪版本是 v2.0.0-20260715142233-9a3f2c1，但 import 路径还是 github.com/user/lib/v2。
立即学习“go语言免费学习笔记（深入）”；
常见误操作：用伪版本拉了 v2 代码，却在代码里写 import "github.com/user/lib"，结果编译报错 no required module provides package —— 因为 Go 查不到那个路径下的包。
- 伪版本 ≠ 免路径约束，它只是版本号的替代品，不改变模块路径规则
- 开发阶段若频繁切分支，建议先打临时 tag（如
v2.0.0-dev.1），比伪版本更易读、更可控 - CI 构建时若用
go mod download验证依赖，必须确保go.sum中记录的是带/v2的完整路径
多主版本共存时 internal/ 包的可见性边界是否跨路径
是独立的。github.com/user/app/internal/utils 和 github.com/user/app/v2/internal/utils 是两个完全隔离的包，即使目录结构相同，彼此也无法导入。
这是因为 Go 的 internal 检查基于完整模块路径，/v2 让它们成了逻辑上不同的模块根。这点常被忽略，导致重构时误以为“只要目录一样就能复用 internal 代码”。
- 如果你真要共享逻辑，要么提取成独立模块（如
github.com/user/shared），要么把公共部分移到不带/vN的顶层路径（如github.com/user/common） - 别试图用
replace把两个v1和v2的internal指向同一物理目录——Go 编译器仍按路径判定权限，会报use of internal package not allowed - 模块路径带
/v2后，go list -m all输出里会出现两行：一行是github.com/user/app，另一行是github.com/user/app/v2，它们互不隶属
/v2 或错配 import 路径，轻则编译失败，重则 silently 使用旧版 API。最麻烦的不是写错，而是改完 go.mod 忘了同步所有 import 语句——这种问题往往只在 CI 或他人拉取代码时才暴露。 
