语义化导入版本控制要求v2+模块必须在导入路径中显式包含版本后缀（如/v2），而非仅靠go.mod声明；否则工具链拒绝构建。v0/v1可省略路径后缀，因其被默认识别。
什么是语义化导入版本控制（Semantic Import Versioning）
Go 模块不是靠 go.mod 里写的版本号来决定导入路径的，而是靠模块路径本身是否包含版本后缀——比如 github.com/user/repo/v2 和 github.com/user/repo 在 Go 看来是两个完全不同的模块，哪怕它们代码一模一样。
这叫“语义化导入版本控制”，核心就一条：**主版本号 v2+ 必须体现在导入路径里**。否则 Go 工具链会拒绝构建，报错类似 require github.com/user/repo: version "v2.0.0" invalid: module contains a go.mod file, so major version must be compatible: should be v0 or v1, not v2。
v2+ 模块必须改导入路径，不能只改 go.mod
很多人以为只要在 go.mod 里写 module github.com/user/repo/v2 就够了，结果其他项目 import "github.com/user/repo" 依然能编译通过——但这是错的，它实际导入的是 v0/v1 版本，根本没走你新发布的 v2。
正确做法是：
立即学习“go语言免费学习笔记（深入）”；
- 把模块根目录的
go.mod第一行改成module github.com/user/repo/v2 - 所有内部
import语句也要同步改成import "github.com/user/repo/v2/xxx"（包括测试文件、内部子包） - 发布 tag 时用
v2.0.0，不是2.0.0或release/v2 - 旧版 v1 保持
github.com/user/repo路径不变，和 v2 并行存在
为什么 v0 和 v1 不需要路径后缀
Go 规定 v0 和 v1 是“隐式版本”：只要模块路径不含 /vN，就默认是 v0（开发中）或 v1（稳定发布）。所以 github.com/user/repo 可以对应 v1.5.0，工具链自动识别。
这个设计是为了降低初版门槛，但也埋了坑：
- 如果你发了
v1.0.0后又想加不兼容变更，不能直接升 v2 并保留原路径——必须切到/v2路径 -
go get github.com/user/repo@v2.0.0会失败，因为路径不匹配；必须go get github.com/user/repo/v2@v2.0.0 - ide 或
go list -m all显示的模块名会带/v2，和 import 路径严格一致
常见踩坑场景和修复方式
最典型的问题是本地开发时混用路径：比如模块已升级为 v2，但某个 .go 文件还写着 import "github.com/user/repo"，编译直接报 import path doesn't contain version 或找不到符号。
排查和修复建议：
- 用
go list -m all | grep repo看当前解析出的实际模块路径，确认是不是带/v2 - 全局搜索项目里所有
import "github.com/user/repo"，替换成import "github.com/user/repo/v2" - 如果用了
replace本地调试 v2，确保replace指向的路径也含/v2，例如replace github.com/user/repo/v2 => ./v2 - CI 构建失败？检查
go mod tidy是否清理掉了旧 import，有时缓存会导致残留
真正麻烦的不是改路径，而是团队协作时有人忘了同步改 import——Go 不会警告，只在构建时报错，而且错误信息不直指问题根源。