Go模块v2+必须在module路径末尾显式添加/v2后缀，如module github.com/user/repo/v2，否则go mod tidy或go build会报错；导入路径也须完全一致，且需打v2.0.0等SemVer tag。
Go 模块 v2+ 路径必须带 /v2 后缀，否则直接报错
Go 从 v1.11 起强制要求：主版本号 ≥ 2 的模块，其 module 声明路径末尾**必须显式包含 /vN（如 /v2、/v3）**。这不是可选项，而是模块系统识别“新主版本”的唯一依据。不加后缀会导致 go mod tidy 或 go build 失败，并抛出类似错误：
invalid version: module contains a go.mod file, so major version must be compatible
这个限制的底层逻辑是：Go 把 github.com/user/repo 和 github.com/user/repo/v2 视为两个完全独立的模块，可以共存、互不干扰。这也是 Go 实现“多主版本并行维护”的基础机制。
- ✅ 正确写法：
module github.com/user/repo/v2 - ❌ 错误写法：
module github.com/user/repo（即使你已打v2.0.0tag） - ⚠️ 注意：
v0和v1不需要后缀（v1是隐式默认），但一旦升到v2，就必须改路径
导入时路径必须与 go.mod 中的 module 完全一致
调用方写 import "github.com/user/repo/v2"，和你的 go.mod 里声明的 module github.com/user/repo/v2 必须一字不差——包括大小写、斜杠位置、有无 v2。任何不一致都会导致构建失败或无法解析依赖。
- 如果你的模块路径是
github.com/user/repo/v2，就**不能**在代码里写import "github.com/user/repo"或import "github.com/user/repo/v2.0" - 内部子包也要同步更新导入路径，比如原
github.com/user/repo/utils需改为github.com/user/repo/v2/utils -
go mod tidy会自动修正本地 import 路径，但只对当前模块生效；跨模块引用仍需手动检查
发布 v2+ 版本 ≠ 创建 Git 分支，而是打符合 SemVer 的 tag
Go 的“版本分支”不是 Git 分支概念，而是一套基于语义化版本（SemVer）+ 路径后缀的发布协议。你不需要为 v2 单独建 release/v2 分支（虽然可以这么做便于开发隔离），但**必须打带 v 前缀的 tag**，例如：
生成周报：读取本机 Git 仓库最近一周的提交记录，按项目分类提炼总结，生成标准周报格式，通过微信推送并返回给用户。触发词：周报、weekly report、git总结、提交记录总结、工作周报。
立即学习“go语言免费学习笔记（深入）”；
-
git tag v2.0.0—— 主版本升级，含不兼容变更 -
git tag v2.1.0—— 新增向下兼容功能 -
git tag v2.1.1—— 仅修复 bug，不改 API
这些 tag 必须推送到远程：git push origin v2.0.0。其他项目执行 go get github.com/user/repo/v2@v2.1.0 才能拉到对应版本。没有 tag，go 工具链只会 fallback 到伪版本（v0.0.0-...），不可靠。
常见坑：v1 和 v2 代码混用、路径未清理、私有仓库配置遗漏
实际迁移中，最容易翻车的是路径残留和环境配置缺失：
- 旧代码里还留着
import "github.com/user/repo"，没改成/v2→ 编译失败或静默使用 v1 -
go.mod里require仍指向 v1 路径，go mod tidy没清干净 → 构建时可能拉错版本 - 模块托管在私有 Git（如公司内网 GitLab），但没配
GOPRIVATE→go get会尝试走 proxy.golang.org，超时或 403 - 忘记在 CI/CD 中设置
GOPRIVATE→ 测试通过，上线却拉不到私有 v2 模块
最稳妥的做法是：改完 go.mod 和所有 import，运行 go mod tidy -v 查看是否还有旧路径残留，再用 go list -m all | grep repo 确认最终解析的模块路径和版本。
