github.com/user/lib/v2和github.com/user/lib能共存，因go将二者视为不同模块：v2必须显式声明module路径为/v2、代码置于/v2子目录、所有import同步更新，否则仍被识别为v1导致冲突。
为什么 github.com/user/lib/v2 和 github.com/user/lib 能共存？
Go 不允许同一模块路径下多个主版本共存，但通过路径分隔实现逻辑隔离：只要模块在发布 v2.0.0+ 时，把主版本号显式加入模块路径（如从 github.com/user/lib 改为 github.com/user/lib/v2），Go 就视其为全新模块。这不是“技巧”，而是 Go Modules 的强制约定。
常见错误是只改了 tag（比如打了 v2.0.0），却没改 go.mod 中的 module 行——这时 Go 仍把它当 v1，不会触发隔离，反而可能因版本冲突导致 go mod tidy 失败或静默降级。
- 必须同步修改三处：
go.mod的module声明、所有import语句路径、以及发布 tag（v2.0.0） - 旧版代码不能直接 import
github.com/user/lib/v2，否则编译报错：cannot find module providing package github.com/user/lib/v2 - v2 模块的
go.mod中go指令声明的是最低兼容 Go 版本，不影响你用 Go 1.22 构建它
go get 升级到 v2+ 时为什么报错 “invalid version”？
典型错误信息是：go get: module github.com/user/lib@upgrade found (v2.1.0+incompatible), but does not contain package github.com/user/lib。这说明你试图用 v2 tag 替换 v1 路径，但模块未按规范切出 v2 路径。
根本原因不是版本号本身，而是模块路径不匹配。Go 在解析 @v2.1.0 时，会尝试找 github.com/user/lib/v2，而实际模块仍声明为 github.com/user/lib，于是找不到包。
- 解决路径只有两个：要么退回 v1 兼容版本（
go get github.com/user/lib@v1.9.0），要么确认对方已发布合规 v2 模块（路径含/v2） -
go list -m -versions github.com/user/lib可查可用版本，但注意：带+incompatible后缀的 v2 版本，代表它没走路径分隔，只是语义上 v2，Go 不认作独立模块 - 不要依赖
replace强行映射 v2 到 v1 路径——这会破坏类型安全，且无法解决导入路径不一致问题
项目里同时用 v1 和 v2 版本，go build 为什么只报一个版本？
因为 Go 的构建图中，每个模块路径只保留一个版本。如果你的代码直接 import github.com/user/lib，又通过第三方依赖间接引入 github.com/user/lib/v2，两者互不干扰——它们是不同路径，自然共存。
真正容易出错的是：你以为自己在用 v2，结果 import 的仍是 v1 路径；或者你升级了某个子模块的 v2，却忘了更新自己代码里的 import 语句，导致编译失败或运行时 panic。
- 检查当前生效版本：
go list -m github.com/user/lib和go list -m github.com/user/lib/v2分别执行，看输出是否都有 - 确认 import 是否写对：v2 版本必须用
github.com/user/lib/v2，少一个/v2就是 v1 - 如果某个依赖强制要求 v1，而你又需要 v2 功能，只能等它升级，或 fork 后用
replace指向你的 v2 分支（但需自行维护兼容性）
大版本升级时，go.mod 的 require 行要不要手动删旧版？
不需要手动删。执行 go get github.com/user/lib/v2@latest 后，go mod tidy 会自动清理未被 import 的 v1 版本（前提是你的代码里已彻底移除对 v1 的 import）。但如果 v1 被其他依赖间接引用，它仍会保留在 require 中——这是正常行为，Go 允许 v1 和 v2 同时存在，只要路径不同。
真正要警惕的是：误删 require 行后运行 go mod tidy，可能把本该保留的 v1 版本也删掉，导致间接依赖失效。
- 推荐操作流：
go get github.com/user/lib/v2@latest→ 修改所有import→go build确认通过 →go mod tidy -
go mod graph | grep lib可查看依赖图中哪些路径实际被加载，比肉眼扫go.mod更可靠 - v2 模块的
go.sum文件会新增对应条目，但 v1 的校验和仍保留——go.sum不做“去重”，只做“记录”
最常被忽略的点：v2 模块的文档、示例、CI 配置是否同步更新。很多团队卡在升级不是因为技术障碍，而是 README 还写着 v1 import 路径，新成员照抄就编译不过。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
