go模块v2+必须改模块路径为/v2等后缀，否则无法被识别和共存；因go不支持同一导入路径下多主版本，需同步更新go.mod和所有import语句，否则编译失败或降级为v1。
Go 模块不向下兼容更新必须发布为新主版本路径，否则无法被正确识别和共存。
为什么 v2+ 必须改模块路径
Go 不支持同一导入路径下多个主版本共存。当你把 github.com/user/lib 从 v1 升级到 v2 并做了破坏性变更（比如删方法、改签名），如果仍用原路径，Go 会认为这是“同一模块的非法降级”，构建直接失败或行为错乱。
真正合规的做法是：在 go.mod 文件里把模块路径显式改为 module github.com/user/lib/v2，并确保所有 import 语句同步改成 "github.com/user/lib/v2"。
- 不改路径只打
v2.0.0tag → Go 无视主版本号，仍当 v1 解析 - 改了路径但没更新 import → 编译报错
cannot find module providing package - 旧代码还在用 v1，新功能要用 v2 → 两者可同时存在于
go.mod中，互不干扰
如何安全过渡 v1 → v2
不能一刀切替换。v1 用户可能大量存在，v2 又不能回退兼容，得靠路径隔离 + 显式迁移来控制节奏。
- 先发布 v2 路径版本（如
github.com/user/lib/v2），文档里明确标注 breaking change - v1 路径继续维护关键 bug 和安全补丁，但停止新增功能
- 在 v2 的 README 或 godoc 里提供 migration guide，例如 “
Do()→DoWithContext(ctx)” - 避免在 v2 中保留 v1 的旧符号做兼容层——这会让接口模糊，增加维护成本
常见误操作：@latest 拿不到 v2
执行 go get github.com/user/lib@latest 默认只会拉取 v1.x 下最新版，哪怕你已经发布了 v2.0.0。因为 @latest 只匹配当前模块路径下的最新 semver 版本，而 v2 是另一个路径。
- 想用 v2？必须写全路径：
go get github.com/user/lib/v2@latest - 想检查是否已有 v2 可用？用
go list -m -versions github.com/user/lib/v2 - 误用
replace github.com/user/lib => github.com/user/lib/v2？会报错：路径不匹配，replace 不接受带/v2后缀的右侧目标
间接依赖卡在 v1 怎么办
你的项目直接用了 v2，但某个依赖（比如 pkgA）仍 require github.com/user/lib v1.5.0，Go 的 MVS 会强制整个项目回落到 v1 —— 这不是 bug，是机制使然。
- 先查源头：
go mod graph | grep user/lib看谁在拉 v1 - 再查原因：
go mod why -m github.com/user/lib输出完整调用链 - 解决路径只有两个：推动
pkgA升级到 v2 兼容版；或用replace强制它用 v2（前提是 v2 确实能跑通其逻辑） - 注意：
replace后必须运行go mod tidy，否则go build仍可能按旧图解析
最易被忽略的一点：v2 路径发布后，CI 流程里所有 go get 命令若没显式指定 /v2，就永远触达不到新版本。这不是配置问题，是 Go 模块设计的硬约束。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
