Go工具链强制要求import路径与磁盘目录结构严格一致，因解析时逐字匹配：module github.com/user/lib/v2必须对应lib/v2/目录，否则go build报错cannot find module；且需同步更新go.mod、所有import语句及子包引用，缺一不可。
Go 语言模块系统对 v2+ 主版本的路径规范不是“建议”，而是强制性解析规则：不改目录结构、不改 import 路径、不改 go.mod 中的 module 声明，go build 就会直接失败。
为什么 import "github.com/user/lib/v2" 必须对应磁盘上的 lib/v2/ 目录
Go 工具链在解析 import 路径时，会按字面匹配模块路径与文件系统路径。它不会做任何“推断”或“重定向”——github.com/user/lib/v2 这个字符串必须能逐段映射到实际目录层级。
- 如果模块声明是
module github.com/user/lib/v2，但代码放在lib/（而非lib/v2/）下，go build会报cannot find module providing package github.com/user/lib/v2 - IDE（如 GoLand）可能“勉强识别”并提供补全，但
go list、go test或 CI 构建必然失败 - 子包引用也必须同步更新：比如原
import "github.com/user/lib/handler"在 v2 中必须改为import "github.com/user/lib/v2/handler"
go.mod 里改了 module 行还不够，必须同步三处
只改 go.mod 是最常见且最致命的遗漏点。模块路径变更本质是一次“重命名操作”，涉及三个强耦合层面：
-
go.mod第一行的module指令：必须是github.com/user/lib/v2（不能是github.com/user/lib加// +build v2等 hack） - 磁盘目录结构：根目录必须是
lib/v2/，且go.mod文件必须位于该目录下 - 所有
import语句：包括本模块内跨子包引用（如lib/v2/handler引用lib/v2/model），路径前缀都得带/v2
私有仓库或 go.work 多模块场景下的典型陷阱
在企业环境里，问题往往藏在配置细节里：
立即学习“go语言免费学习笔记（深入）”；
-
go.work文件若仍指向旧的顶层目录（如./），而不是./lib/v2，会导致go run找不到主模块 - 私有仓库未配
GOPRIVATE，go get github.com/user/lib/v2@v2.1.0会卡在代理校验，报错信息里常含401 Unauthorized或no matching versions - 本地缓存残留旧版本：执行
go clean -modcache后再go mod tidy，否则go.sum可能混入 v1 的校验和，导致构建不一致
最容易被忽略的是子包 import 路径——很多人只改了外部用户的导入语句，却忘了自己模块内部的跨包引用也要加 /v2。这种错误不会在 go build 阶段立刻暴露，而是在运行时或测试中因类型不兼容（如 v1.Config 和 v2.Config 视为不同类型）才突然崩掉。
