go模块v2+主版本升级本质是创建新模块，需同步修改module路径（含/v2）、目录结构（/v2子目录）、所有import语句（加/v2）及go get命令（指定/v2路径），四者缺一不可。
Go 模块主版本升级（v2+）不是“升级”，而是引入一个新模块——路径、目录、导入语句全都要变，否则编译直接失败。
module 路径必须带 /v2 且与本地子目录严格对应
Go 官方强制要求 v2+ 模块在 go.mod 中显式声明主版本后缀，例如：module github.com/user/repo/v2。这不只是命名习惯，而是模块识别的硬性规则。
- 错误写法：
module github.com/user/repo→ 即使代码已改，Go 仍视其为 v1 模块 - 正确结构：仓库根目录下必须存在
/v2/子目录，所有源码放在里面（如v2/pkg/client.go） -
go mod tidy不会帮你建目录或挪文件，它只按module声明找包 —— 路径声明是/v2，但代码还在./pkg？cannot find package
所有 import 语句必须手动批量替换
go mod tidy 会更新 require 行里的版本和路径，但绝不会碰源码里的 import 语句。这是最常被忽略、导致编译中断的点。
- 旧导入：
import "github.com/user/repo"→ 必须全部改为import "github.com/user/repo/v2" - 子包同理：
"github.com/user/repo/client"→"github.com/user/repo/v2/client" - 内部相对导入（如
import "./internal/util"）不受影响，但跨模块引用一律要带/v2 - 建议用
sed或 IDE 的全局替换（确认无误后再提交），别靠人眼扫
go get @latest 不会跨主版本，必须显式指定路径
go get -u 或 go get github.com/user/repo@latest 永远只拉 v1 分支的最新版。想用 v2？路径里就得写清楚。
- 安全升级命令：
go get github.com/user/repo/v2@latest - 锁定 patch 版本更稳妥：
go get github.com/user/repo/v2@v2.3.1 -
@latest取的是最近 tag，不是main分支；没打 tag 的 commit 不会被选中 - 运行
go list -m -u all只能看到 v1 是否可升，看不到 v2 —— 因为它是独立模块
v1 用户完全感知不到 v2，兼容需主动设计
v2 对老用户透明：他们 go get github.com/user/repo 拿到的永远是 v1。你无法“推送升级”，只能靠策略过渡。
- 双版本并存是常见做法：v1 维护 bugfix，v2 开发新特性，文档明确标注 breaking change
- 不推荐长期用
replace硬绑 v2 路径 —— 它绕过模块系统，go list -u查不到，CI 易漏检 - 如果 v2 是 breaking 大改，务必在 README 和 GitHub Release 里写清迁移步骤，尤其涉及接口签名、错误类型、配置结构变更
主版本升级真正麻烦的从来不是命令怎么敲，而是路径、目录、导入、依赖四者必须同步对齐；差一个斜杠或少一个 /v2，编译器就拒绝合作。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
