Go v2升级必须同步修改module路径、import语句和目录结构，三者缺一不可，否则因路径不匹配导致cannot find package错误。
不能靠“加个兼容层”就完事——Go 的向下兼容是路径、版本、导入三者强绑定的结果，改错一个环节，下游立刻编译失败。
为什么 v2 升级后旧代码直接报错 cannot find package
根本原因不是代码没改，而是 Go 工具链压根没把新路径当回事。你打了 v2.0.0 tag、改了 go.mod 里的 module github.com/user/repo/v2，但只要源码里还写着 import "github.com/user/repo"，Go 就只认 v1 路径，不会自动映射到 /v2。
常见错误现象：
- 执行
go build报cannot find package "github.com/user/repo"，但go list -m all显示已拉取v2.0.0 - 用
go get github.com/user/repo@v2.0.0失败，提示unknown revision v2.0.0 - 本地
v2/目录下go mod init成功，但主项目go build ./...仍试图从根目录找包
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 必须把 v2 代码物理移到
v2/子目录（不能是version2/或next/） -
v2/go.mod中的module行必须为module github.com/user/repo/v2，末尾/v2缺一不可 - 所有调用方代码里的
import必须手动批量替换：从"github.com/user/repo"改成"github.com/user/repo/v2" - 不要依赖
replace在主模块里“模拟”v2——这会让go list -m all显示路径混乱，CI 构建时失效
如何让 v1 和 v2 在同一仓库共存且互不干扰
Go 不允许“同一路径多个版本”，但允许“同一仓库多个路径”。关键不在 Git tag，而在目录结构和 go.mod 声明是否严格隔离。
正确结构只有这一种：
github.com/user/repo/
├── go.mod // module github.com/user/repo
├── main.go
├── utils/
│ └── helper.go // import "github.com/user/repo/utils"
└── v2/
├── go.mod // module github.com/user/repo/v2
├── main.go
└── utils/
└── helper.go // import "github.com/user/repo/v2/utils"
容易踩的坑：
- v2 代码放在
./v2但v2/go.mod还写module github.com/user/repo→ Go 当作 v1 的子目录，不是独立模块 - 根目录和
v2/共用同一个go.sum→go mod tidy会互相污染，必须各自运行 - 想让 v1 用户“无感升级”而提供
github.com/user/repo/compat包 → 这仍是 v1 路径，无法解决 v2 API 不兼容问题，纯属误导
go.mod 里 go 指令和 toolchain 指令怎么设才不影响兼容性
go 指令声明的是源码语言特性底线，toolchain 指令声明的是构建工具底线——两者不等价，设错会导致老环境编译失败或新特性被禁用。
例如：
- 设
go 1.26但用户还在用 Go 1.24 →go build直接拒绝，哪怕代码里没用 1.26 新语法 - 设
toolchain go1.21.0但 CI 机器装的是 Go 1.25 → 构建照常进行，只是忽略该指令（Go 1.21+ 工具链向下兼容） - 设
go 1.19+toolchain go1.26.0是安全组合：源码兼容旧环境，构建可用新优化器
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 库项目优先设
go为当前稳定版前一个次要版本（如 Go 1.25 发布后，新库默认写go 1.24） -
toolchain可设为团队实际使用的最低构建工具版本，不必追新，但别低于 Go 1.21（否则不识别该指令） - 不要在
go.mod里写// +build ignore类注释来“绕过”版本检查——Go 不解析这类注释做版本决策
最常被忽略的一点：兼容性不是由 go.mod 单独决定的，而是由 module 路径 + import 语句 + 目录结构 + tag 命名 四者共同锁定的。少改一个，下游就可能陷入“能 go get 但编译不过”的状态。
