Go模块升级v2必须将module路径改为github.com/user/repo/v2并同步更新所有import语句，否则Go仍识别为v1；v2代码须置于v2/子目录且独立运行go mod init，不可混放或绕过路径规范。
Go模块路径从v1升级到v2必须改module声明
不改go.mod里的module行，Go根本不会识别这是v2——它只会继续当v1用，哪怕你本地打的是v2.0.0 tag。Go的版本识别完全依赖模块路径后缀，不是靠tag名、不是靠文件夹名、也不是靠go version输出。
实操建议：
- 原路径是
github.com/user/repo，v2必须改成github.com/user/repo/v2（注意末尾/v2） - 所有内部
import语句也要同步更新，比如import "github.com/user/repo"→import "github.com/user/repo/v2" - 别试图用
replace在本地绕过——下游项目go get时仍会拉错版本，且go list -m all会显示不一致的模块路径
go get默认不自动升级到v2，得显式指定路径
go get github.com/user/repo永远只拉v0或v1，哪怕v2已发布。Go工具链默认忽略路径中未声明的次版本，这是设计使然，不是bug。
常见错误现象：执行go get github.com/user/repo@v2.0.0报错unknown revision v2.0.0——因为没加/v2后缀，Go去github.com/user/repo下找tag，当然找不到。
立即学习“go语言免费学习笔记（深入）”；
正确做法：
- 用完整模块路径：
go get github.com/user/repo/v2@v2.0.0 - 或者用
go get+ 本地路径：go get ./v2（如果v2代码在v2/子目录） - 如果项目还没发布v2 tag，先
git tag v2.0.0 && git push origin v2.0.0，再go get
同一仓库共存v1和v2需严格隔离目录结构
Go要求v1和v2代码物理隔离：v1在根目录，v2必须在v2/子目录（或其他带版本号的子目录），且v2/go.mod的module必须是github.com/user/repo/v2。混放会导致go build失败或导入冲突。
使用场景：维护老项目（依赖v1）的同时开发v2新功能，不能中断v1用户。
容易踩的坑：
- 把v2代码放在
pkg/v2/这种非模块根目录——go mod init会生成错误路径，import也对不上 - 忘记在v2子目录里运行
go mod init github.com/user/repo/v2，导致go.mod路径仍是github.com/user/repo - v2子目录里引用了根目录下的
internal/包——Go不允许跨模块引用internal，会报use of internal package not allowed
go.sum里v1和v2的校验和独立存储，不可复用
go.sum按模块路径+版本号唯一索引，github.com/user/repo v1.5.0和github.com/user/repo/v2 v2.0.0是两条完全无关的记录。删掉其中一条不会影响另一条，但手动编辑go.sum极易破坏校验，引发checksum mismatch。
性能与兼容性影响：
- 下游项目同时依赖v1和v2时，Go会分别下载两份代码，磁盘占用翻倍，
go list -m all会显示两个条目 - v2的
go.mod若用了更高版本的Go（如go 1.21），而老项目用go 1.19构建，可能触发go: incompatible module requires go 1.21 - CI里若缓存
go.sum但没清空vendor/，旧v1依赖可能意外被v2覆盖，导致测试通过但线上出错
路径变更不是改个名字就完事——模块路径是Go模块系统的锚点，牵一发而动全身。最常被忽略的是import语句同步更新和v2/子目录的go mod init执行时机，这两个动作漏掉一个，整个升级就卡在“看似成功、实际失效”的状态。
