go mod tidy报“require…incompatible dependencies”是因主模块声明版本与依赖约束冲突，需用go list -m all和go mod graph定位冲突源，优先升级依赖方或修正v2+路径，而非删go.sum或硬改go.mod。
Go 本身不支持“同一模块多个版本同时加载”，所谓“多版本共存”实际是指项目中不同依赖各自声明的版本能被正确解析并满足构建要求——不是靠强制保留多个版本，而是靠 Go Modules 的版本选择机制和路径隔离规则来达成兼容。关键不在“下载多个”，而在“如何让 go mod tidy 不冲突”。
go mod tidy 报错 “require …: version … has incompatible dependencies” 怎么办
这是最常见但被误解的报错。它不是说你本地没装那个版本，而是当前主模块的 go.mod 里某个 require 声明的版本，与它所依赖的其他模块的约束发生冲突。
- 先运行
go list -m all | grep -E "(your-module|conflicting-module)"，确认实际选中的版本号 - 用
go mod graph | grep your-module查谁拉进了冲突版本 - 不要直接删
go.sum或手动改go.mod—— 这会破坏校验和，下次go build可能失败 - 优先尝试
go get module@latest升级依赖方，很多老模块已适配新版本但未更新go.mod
为什么 v2+ 版本必须改模块路径（如 /v2）
Go Modules 的版本识别完全依赖模块路径字符串。如果一个模块发布 v2.0.0 却没在 go.mod 中写 module github.com/user/lib/v2，Go 就认为它还是 v1，不会与 v1 共存，反而可能因 API 破坏导致编译失败。
- 错误示例：
module github.com/user/lib+require github.com/user/lib v2.0.0→ Go 拒绝解析 - 正确做法：v2 起必须带
/v2后缀，且所有 import 语句同步改为github.com/user/lib/v2 - v3、v4 同理，路径必须唯一对应 major 版本，否则
go mod tidy会报invalid version
replace 和 exclude 的真实作用边界
replace 是开发期临时替换依赖源，exclude 是强制剔除某个版本——但两者都不能绕过 Go 的单版本选择规则，也不能解决根本兼容问题。
-
replace github.com/old/lib => ./fork只影响当前模块构建，下游项目仍会走原始路径 -
exclude github.com/bad/lib v1.2.3不是“禁用”，而是告诉 Go：“别选这个版本”，但它仍可能被其他依赖间接拉入 - 真正生效的前提是：被
replace或exclude的模块，在整个依赖图中没有其他路径强制 require 它 - CI 中应禁用
replace，否则测试环境与生产不一致
go.mod 中的 go 指令影响什么
go 1.22 这行只声明最低 Go 运行时兼容版本，不控制依赖下载行为，也不限制你用更高版本构建。
- 它只在
go build时校验：若当前go命令版本低于 1.22，直接报错退出，不尝试降级 - 它不影响
go mod download或go list -m的结果 - 如果你用
go1.26.2构建一个go 1.22的项目，一切正常；反过来则失败 - 别把它当成“锁版本”用——想锁依赖请用
go mod vendor或 pinned checksums
最容易被忽略的是：模块路径是否带 /vN 决定了 Go 是否认为它是独立模块；而 go.mod 文件是否被正确 commit 到对应 tag 分支，决定了别人 go get 时能否解析到你期望的版本。这两点不满足，再多的 replace 都只是临时止痛。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
