主版本冲突本质是导入路径不一致，v1与v2为完全独立模块；需统一import路径并修改go.mod中require声明，replace无法跨路径映射，go mod tidy对此无能为力。
主版本冲突（v1 vs v2）不是“版本号不同”，而是导入路径不一致
Go 模块系统里，v2 不是 v1 的升级版，而是**完全独立的模块**。只要 go.mod 里声明了 github.com/example/lib/v2，它和 github.com/example/lib（即 v1）在 Go 看来就是两个不同包，互不兼容、无法共用类型、不能互相赋值。
常见错误现象：cannot use example.User as example.User (types from different modules)，哪怕结构体一模一样，只要导入路径带 /v2 就算另一个世界。
- 检查是否混用：运行
go list -m all | grep example/lib，若同时出现github.com/example/lib和github.com/example/lib/v2，说明项目里已引入两个主版本 - 确认调用链：用
go mod why -m github.com/example/lib/v2查清谁在拉v2；同理查v1被谁依赖 - 修复方式只有两种：要么统一迁移到
v2（改所有import "github.com/example/lib"为"github.com/example/lib/v2"），要么让所有依赖都降级/锁定到v1（前提是上游支持且你不需要v2新特性） - 注意：不能用
replace github.com/example/lib => github.com/example/lib/v2—— 这会破坏路径匹配，导致 import 解析失败
分支版本（+incompatible）本质是语义化版本失效，需人工干预
当模块没打 v1.2.3 这类标准 tag，只在 main 或 develop 分支上开发时，Go 会生成类似 v0.0.0-20231015120000-abcdef123456 的伪版本，并标记为 +incompatible。这类版本不参与 MVS 兼容性判断，极易引发冲突。
典型表现：go mod tidy 随机切换 commit、CI 构建结果不一致、go.sum 反复变动。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 定位来源：执行
go mod graph | grep 'example/lib.*incompatible'找出哪个依赖在拉+incompatible版本 - 优先推动上游打正式 tag；若不可行，可用
go get github.com/example/lib@commit-hash锁定具体 commit，再go mod tidy - 避免在
go.mod中写死// +incompatible注释 —— 它不会阻止其他地方拉入不同 commit，只是掩盖问题 -
replace对+incompatible有效，但必须指向同一仓库的明确 commit 或 tag，例如：replace github.com/example/lib => github.com/example/lib v0.0.0-20231015120000-abcdef123456
require 与 replace 在主版本场景下的行为边界
require 是声明“我需要这个模块的这个版本”，而 replace 是重写“当我 import 这个路径时，实际去哪找代码”。两者在主版本场景下作用完全不同。
错误用法：replace github.com/example/lib => github.com/example/lib/v2 —— Go 无法将 import "github.com/example/lib" 映射到 v2 路径，因为导入路径本身不含 /v2，替换后仍找不到包。
- 正确做法：要使用
v2，必须改代码里的import语句，再执行go get github.com/example/lib/v2@latest，让require行出现在go.mod中 -
replace只适用于路径相同但源不同的场景，比如：replace github.com/example/lib/v2 => ./local-fix/v2（本地调试）或replace github.com/example/lib/v2 => git.example.com/internal/lib/v2（私有镜像） - 如果多个子模块（如
/cmd/a和/cmd/b）分别 requirev1和v2，整个 module 无法构建 —— Go 不允许同一 module 内共存不兼容主版本，必须统一路径或拆分成独立 module
go mod tidy 为什么对主版本冲突“无能为力”
go mod tidy 的核心逻辑是 MVS（最小版本选择），但它只在**同一导入路径下**做版本协调。一旦出现 lib 和 lib/v2 这种路径分裂，MVS 就彻底失效 —— 它不认为这是“同一模块的不同版本”，而是两个完全独立的模块，因此不会尝试统一、也不会报错，只是默默把两者都拉进来。
结果就是：编译可能通过，但运行时 panic，或者接口实现错位（比如 v1.Interface 和 v2.Interface 虽然名字一样，但类型不等价）。
- 真正有效的检查命令是：
go build -o /dev/null ./...—— 强制全量编译，比tidy更早暴露类型不匹配 - CI 中应加入
go list -m all | grep -E 'example/lib(/v[0-9]+)?' | wc -l，若输出 >1，说明存在主版本混用，应阻断 - 别依赖
go.sum是否干净 —— 它可以同时存lib和lib/v2的校验和，看起来“合法”，实则危险
+incompatible 也不是临时方案，而是语义化版本承诺的缺失。最易被忽略的点在于：**你写的 import 路径，就是模块身份的唯一标识，改它比改版本号重要十倍**。 
