go要求v2+模块路径必须包含/v2后缀，因此go get github.com/user/repo@v2.0.0失败，正确命令是go get github.com/user/repo/v2@v2.0.0，且module声明、import路径、tag均需严格匹配/v2。
为什么 go get github.com/user/repo@v2.0.0 会失败
因为 Go 不认这个路径——v2.0.0 是版本号，但模块路径本身没带 /v2。工具链看到 github.com/user/repo 就默认它是 v0/v1 模块，而你传的却是 v2 版本，直接报错：version "v2.0.0" invalid: module contains a go.mod file, so major version must be compatible: should be v0 or v1, not v2。
这不是网络问题，也不是权限问题，是路径语义不匹配。
- 正确命令是：
go get github.com/user/repo/v2@v2.0.0 - 如果本地已有该模块，且
go.mod里写的是require github.com/user/repo v2.0.0，go mod tidy会失败并提示路径缺失/v2 - IDE（如 VS Code + Go extension）在依赖列表里显示的模块名也会是
github.com/user/repo/v2，和 import 路径严格一致
import "github.com/user/repo" 和 import "github.com/user/repo/v2" 是两个模块
Go 工具链把它们当完全不同的包处理：符号不共享、类型不兼容、不能混用。哪怕代码内容一字不差，repo/v2 的 Client 类型和 repo 的 Client 类型在编译期就是不同类型。
- 旧版 v1 保持路径
github.com/user/repo不变，可继续维护 - v2 必须所有内部 import 全部改成
github.com/user/repo/v2/xxx，包括internal/、test、cmd/下的所有文件 - 如果某个
.go文件漏改，编译时会报import path doesn't contain version或找不到符号（比如undefined: repo.NewClient）
go.mod 第一行 module 声明必须和 import 路径一致
module github.com/user/repo/v2 不只是“声明版本”，它定义了整个模块的根路径。所有子包（如 github.com/user/repo/v2/http）都从这个前缀派生。
- 若写成
module github.com/user/repo却发布 v2 tag，go list -m all会显示github.com/user/repo v2.0.0，但实际 import 仍走 v1 路径 - 发布 tag 必须是
v2.0.0（带v前缀），不是2.0.0或release/v2 -
go mod init后第一件事就是确认这行是否含/v2；改完后立即运行go mod tidy，它会帮你发现残留的旧路径引用
v0 和 v1 为什么不用加路径后缀
这是 Go 的隐式约定：github.com/user/repo 这个路径天然对应 v0（开发中）或 v1（稳定版）。只要没出现 /v2，工具链就认为你还在 v1 生命周期内。
所以如果你发了 v1.5.0，又做了破坏性变更，不能只改 go.mod 里的版本号升到 v2.0.0 —— 必须切路径、改 import、打新 tag，三者缺一不可。
最常被忽略的是：v2 模块发布后，v1 路径仍可独立存在、继续打 v1.6.0 补丁。两者互不影响，但使用者必须显式选择走哪条线。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
