Go模块主版本不一致报错无法绕过，必须显式区分导入路径：v1和v2是两个完全不同的模块，需将import "github.com/some/lib"改为import "github.com/some/lib/v2"并同步更新go.mod中依赖声明。
Go 模块主版本不一致报错无法“绕过”，必须显式区分导入路径——v1 和 v2 是两个完全不同的模块，不能共存于同一 import 语句中。
为什么 import "github.com/some/lib" 会报错：found versions v1.5.0, v2.3.0？
这不是 Go 的 bug，而是语义化版本（SemVer）的强制约束：当某个依赖要求 github.com/some/lib/v2，而你的代码仍写 import "github.com/some/lib"（即 v1 路径），Go 会同时加载两个路径——github.com/some/lib 和 github.com/some/lib/v2。但若两者内部结构相似（比如都导出 Log 类型），编译器就会报 ambiguous import 或类型不匹配错误。
- 错误典型提示：
cannot use X as type Y (possible import cycle)、undefined: somepkg.NewClient、或found versions v1.x, v2.x在go list -m all输出中并列出现 - 根本原因：v2+ 主版本必须体现在导入路径末尾，即
/v2、/v3；否则 Go 认为它是 v0/v1，与 v2 模块视为冲突而非升级 - 常见诱因：第三方库已发布 v2，但你项目里仍有旧版代码未更新 import 路径；或某依赖（如测试工具、linter）悄悄拉了 v1，而你主逻辑用了 v2
怎么确认当前项目到底在用哪几个主版本？
别猜，直接查真实加载的模块路径和版本：
- 运行
go list -m -f '{{.Path}} {{.Version}}' all | grep some/lib—— 看输出是否同时含github.com/some/lib和github.com/some/lib/v2 - 查谁在拉 v1：
go mod graph | grep 'some/lib@' | grep -v '/v2'，再配合go mod why -m github.com/some/lib追溯调用链 - 特别注意：ginkgo、gomega、mockgen 等测试/生成工具常隐式依赖旧版，它们不会出现在你自己的
require里，但会污染依赖图
修复动作必须分两步：改代码 + 改依赖声明
只改 go.mod 或只改 import 都不行，二者必须同步：
立即学习“go语言免费学习笔记（深入）”；
- 把所有
import "github.com/some/lib"替换为import "github.com/some/lib/v2"（注意路径末尾/v2） - 执行
go get github.com/some/lib/v2@latest（或指定版本），确保go.mod中新增/更新的是github.com/some/lib/v2 v2.3.0这一行，而不是github.com/some/lib v1.5.0 - 删掉旧的
require github.com/some/lib v1.x行（go mod tidy通常会自动清理，但建议手动核对） - 如果上游依赖（如
pkgA）还没升级到 v2，且你又必须用它，只能暂时用replace github.com/some/lib => github.com/some/lib/v2—— 但这是临时方案，replace不会改变pkgA内部 import 路径，所以大概率仍会失败
最容易被忽略的坑：vendor 目录和 CI 构建环境
本地能跑 ≠ 构建通过，尤其在 go mod vendor 后：
- 检查
vendor/modules.txt是否同时列出github.com/some/lib和github.com/some/lib/v2—— 如果有，说明 vendor 没 clean 干净，先rm -rf vendor再go mod vendor - CI 中若复用旧缓存，可能残留 v1 的
go.sum条目，导致校验失败；建议在 CI 步骤开头加go clean -modcache - 不要用
exclude github.com/some/lib v1.5.0试图“屏蔽”旧版——exclude 只阻止该版本被选中，但若某依赖硬编码 require v1.5.0，构建仍会失败
主版本不一致不是版本号“太新”或“太旧”的问题，是路径契约的断裂。改 import 路径这件事，看起来只是加个 /v2，但它决定了 Go 模块系统是否把你当成在用同一个东西——而这恰恰是整个依赖解析的起点。
