Go modules通过模块路径中的/vN标识主版本，v2+需显式包含/v2路径，否则标记为+incompatible；go get -u默认只升次版本，跨主版本须手动修改路径与require；replace/exclude无法解决兼容性本质问题。
Go modules 默认如何解析版本号
Go 的 go.mod 文件里写的是语义化版本（SemVer），但 Go 并不严格校验 MAJOR.MINOR.PATCH 格式 —— 它只关心前导数字和是否带 v 前缀。比如 v1.2.3、v1.2.0-rc.1、v2.0.0+incompatible 都能被识别，但含义不同。
关键点在于：Go 用主版本号（v1、v2）决定模块路径是否独立。一旦模块发布 v2.0.0 及以上，且模块路径未显式包含 /v2，Go 就会自动加 +incompatible 标记，表示“这个 v2 版本没走标准路径，可能破坏兼容性”。
-
v1.5.0→ 兼容所有v1.x.y（只要没打+incompatible） -
v2.0.0且路径仍是example.com/foo→ 自动变成v2.0.0+incompatible，Go 不保证向后兼容 -
v2.0.0且路径是example.com/foo/v2→ 独立模块，可与v1共存
为什么 go get -u 有时升级出错
执行 go get -u 时，Go 会尝试升级到最新**次要版本**（如从 v1.2.3 升到 v1.5.0），但不会跨主版本（比如不自动从 v1 升到 v2）。如果依赖树里混了 v1 和 v2+incompatible，就容易触发 version conflict 错误。
常见报错：go: example.com/lib@v2.1.0+incompatible requires example.com/dep@v1.0.0, but that version is excluded by pattern matching
立即学习“go语言免费学习笔记（深入）”；
- 根本原因是
+incompatible版本不参与 Go 的标准兼容性推导，它被当作“非 SemVer 模块”处理 -
go get -u=patch更安全，只升PATCH（如v1.2.3→v1.2.4） - 若需升级主版本，必须手动修改
go.mod中的 require 行，并确认导入路径是否已更新（比如从"example.com/lib"改为"example.com/lib/v2"）
如何正确发布一个 v2 模块
不是简单改 go.mod 里的 module 行或打个 v2.0.0 tag 就完事。Go 要求主版本号必须体现在模块路径中，否则就降级为 +incompatible。
步骤必须按顺序来：
- 把
go.mod中的module example.com/foo改成module example.com/foo/v2 - 所有内部
import语句也要同步改成"example.com/foo/v2"（包括测试文件） - 打 Git tag：
git tag v2.0.0（注意：仍是v2.0.0，不是v2.0.0/v2） - 确保 CI 或用户运行
go get example.com/foo/v2能正常拉取 —— 这才是真正的 v2 模块
漏掉路径变更，哪怕 tag 写对了，Go 仍当它是 v1 的补丁，后续升级会混乱。
replace 和 exclude 不是版本兼容的解法
遇到冲突时，有人倾向用 replace example.com/lib => ./local-fork 或 exclude example.com/lib v1.9.0 强行绕过。但这只是掩盖问题，不是管理兼容性。
-
replace仅在本地或私有构建中生效，无法被下游模块复用；CI 和他人go build会失败 -
exclude只阻止特定版本被选中，不解决依赖图中多个版本共存导致的符号冲突（比如两个包都 import 了同一依赖的不同 incompatible 版本） - 真正可控的方式是：统一主版本路径 + 显式约束
require+ 用go list -m all检查实际解析结果
模块路径里的 /vN 是 Go 兼容性契约的物理载体，跳过它，就等于放弃 Go modules 的版本隔离机制。
