Go模块v2+必须显式带/v2等版本后缀，因Go模块系统要求路径体现主版本以隔离不兼容变更，如module github.com/user/lib/v2对应import "github.com/user/lib/v2"且目录须为lib/v2。
go.mod 里出现 github.com/user/lib 和 github.com/user/lib/v2 是正常现象
这不是冲突，是 Go 的语义化版本隔离机制在工作。只要 v2 模块在发布时把模块路径改成了 module github.com/user/lib/v2，Go 就会把它当作一个全新模块处理，和 v1 完全无关。
常见错误是看到两个版本就去删掉其中一个，结果导致某个依赖编译失败——因为 A 依赖 v1 的 API，B 依赖 v2 的新接口，两者根本不能互相替代。
-
go list -m all | grep lib能快速确认是否真有多个主版本共存 -
go mod graph | grep lib可定位谁引入了v1、谁拉了v2 - 如果
v2没加路径（比如仍用module github.com/user/lib），那 Go 会拒绝识别它为 v2，后续所有引用都会混乱
import 路径必须和模块路径严格一致
你代码里写 import "github.com/user/lib"，就只能用 v1；要调 v2，必须显式写成 import "github.com/user/lib/v2"。Go 不会自动映射，也不会做任何兼容转换。
容易踩的坑是：只改了 go.mod 里的 require github.com/user/lib/v2 v2.3.0，但没改代码里的 import，结果编译报错 cannot find package "github.com/user/lib/v2" —— 实际是因为 import 还是旧路径，根本没触发 v2 的加载。
立即学习“go语言免费学习笔记（深入）”；
- 升级前先全局搜索替换
import "github.com/user/lib"→import "github.com/user/lib/v2" - v2 包里导出的函数名、结构体字段、方法签名很可能已变，不能指望“重命名一下就能跑”
- 如果项目里既有直接 import v1，又有间接依赖带 v2，
go build会同时加载两者，互不干扰
go get @latest 可能跳到 /v3，但不会自动帮你改 import
执行 go get github.com/user/lib@latest 时，如果远程最新 tag 是 v3.0.0 且路径含 /v3，Go 会尝试升级到那个版本；但如果当前代码仍用 import "github.com/user/lib"，就会编译失败——因为 Go 找不到 v3 对应的 import 路径。
更危险的是：如果该库没按规范发 /v3，而是直接打 v3.0.0 tag 但路径仍是 module github.com/user/lib，Go 会拒绝加载并报错 invalid version。
- 稳妥做法是：先手动改 import 和调用代码，再运行
go mod tidy -
go get -u=patch只升补丁版，不会跨主版本，适合保守更新 - CI 中建议固定 Go 版本（如
1.21.10），不同 Go 版本对 MVS（最小版本选择）策略的实现有细微差异，可能导致go.sum波动或版本解析不一致
replace 不是解决主版本冲突的方案
replace 是开发阶段临时绕过远端模块的手段，比如调试本地 fork 分支。但它不能解决“v1 和 v2 同时存在”的问题，反而会让事情更糟——它强制整个模块树都走同一路径，可能让原本该用 v2 的依赖被迫降级到 v1，引发运行时 panic。
真正需要的是明确区分使用场景：哪些子模块必须用 v1，哪些可以/必须用 v2。如果某个老依赖死活不升级，又无法替换，唯一出路是推动它发一个兼容分支（如 v1-compat），或者自己维护一个桥接层。
- 用完
replace务必删掉，再跑一遍go mod tidy确认无异常 - 生产构建中残留
replace行，等于放弃校验和验证，安全链就断了 - 多模块仓库（如
/cmd/a和/lib/b各自有 go.mod）可各自 require 不同主版本，这是合法且受支持的隔离方式
