主版本升级必须改模块路径，否则go拒绝解析；正确做法是将module声明改为github.com/user/lib/v2，并同步更新所有import为github.com/user/lib/v2，漏改即编译失败。
主版本升级必须改模块路径，否则 Go 拒绝解析
Go 不允许 v2.0.0 仍用 module github.com/user/lib 这种写法。它会直接报错：invalid version: go.mod has non-semver version 或 require github.com/user/lib: version "v2.0.0" invalid。这不是警告，是硬性拦截。
正确做法只有两个步骤：
- 在新分支或新目录中，把
go.mod第一行改成module github.com/user/lib/v2 - 所有调用方的 import 必须同步改为
import "github.com/user/lib/v2"
漏改任意一处 import，编译就会失败 —— Go 不会自动映射或 fallback。
同一项目可同时存在 v1 和 v2，但前提是路径隔离
github.com/user/lib（v1）和 github.com/user/lib/v2（v2）在 Go 看来是两个完全独立的模块，互不干扰。你可以：
- 在
/cmd/app1中 importgithub.com/user/lib（v1.5.0） - 在
/cmd/app2中 importgithub.com/user/lib/v2（v2.1.0） - 甚至在同一个
.go文件里同时 import 两者（只要不混用类型）
但注意：如果两个版本导出相同名称的类型（如 type Config struct{}），且你在代码中把它们当同一类型传参或赋值，就会触发编译错误：cannot use ... as ... value in assignment —— 这不是版本冲突，是类型系统严格区分的结果。
go get @latest 不会跨主版本，v1 的项目永远拉不到 v2
执行 go get github.com/user/lib@latest 时，Go 默认只找 v1.x.x 范围内的最新版（比如 v1.9.3），不会跳到 v2.0.0。这是语义化版本规则 + MVS 算法共同决定的。
想主动升级到 v2，必须显式指定：
-
go get github.com/user/lib/v2@latest（前提是模块路径已更新） - 或
go get github.com/user/lib/v2@v2.1.0
如果你看到 go list -m -versions github.com/user/lib 列出了 v2.0.0 却拉不到，大概率是本地 go.mod 还在引用旧路径，或者远程仓库没打 v2.0.0 标签（Git tag 必须是 v2.0.0，不能是 2.0.0 或 release/v2）。
replace 无法绕过路径规则，v2 的 import 必须匹配模块路径
有人试图用 replace github.com/user/lib => github.com/user/lib/v2 让 v1 项目“透明”升级，这行不通。Go 在解析 import 时先查路径，再查 replace；import "github.com/user/lib" 永远不会命中 replace github.com/user/lib/v2 => ... 这条规则。
真正有效的 replace 写法只能是：
-
replace github.com/user/lib/v2 => ./local/v2-fix（调试 v2 分支） -
replace github.com/user/lib => ./local/v1-backport（给 v1 打补丁）
关键点：replace 左侧必须和 import 路径完全一致，包括 /v2 后缀。写错一个字符，go mod tidy 就不会生效。
主版本二次迭代最易被忽略的点：不是怎么发版，而是下游是否已准备好切换 import 路径。一旦发布 v2，所有依赖它的项目都得改代码、跑测试、验证行为一致性 —— 这个成本无法靠工具规避。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
