主版本升级必须改module路径，因为Go将不同主版本视为独立模块；不改路径会导致导入冲突、构建失败或静默覆盖，如go get失败、编译报错“cannot load”或意外降级使用v1版本。
主版本升级为什么必须改 module 路径？
因为 Go 把不同主版本（v1、v2、v3）视为完全独立的模块，不是“同一模块的升级”，而是“新模块”。不改路径会导致导入冲突、构建失败或静默覆盖——Go 会拒绝解析歧义。
- Go 的模块系统设计原则是：**语义化主版本变更 = 不兼容 API 变更 = 新模块**
-
go.mod中的module声明即模块唯一标识，等同于导入路径前缀。例如module github.com/user/lib对应import "github.com/user/lib"；而v2版本必须声明为module github.com/user/lib/v2，对应import "github.com/user/lib/v2" - 如果不加
/v2，Go 工具链会认为你仍在发布v0或v1兼容版本，强行打v2.0.0tag 会被忽略，或触发invalid version: go.mod has post-v1 module path "github.com/user/lib" at revision v2.0.0错误
不改路径的实际后果有哪些？
你以为只是换个版本号，实际会立刻暴露在构建链路里：
- 下游项目
go get github.com/user/lib@v2.0.0会失败，报错：unknown revision v2.0.0或malformed module path - 即使手动编辑
go.mod强行写入require github.com/user/lib v2.0.0，go build时也会提示：cannot load github.com/user/lib: module github.com/user/lib@latest found (v1.5.0), but does not contain package github.com/user/lib—— 因为编译器按路径找包，而v2代码根本不在github.com/user/lib下 - 更隐蔽的问题：若旧版未归档、新版又没加
/v2，Go 可能降级选择v1.x的某个 patch 版本，导致你“以为升了 v2”，实则用的还是 v1 的行为
怎么安全地发布一个 v2 模块？
不是改个 tag 就完事，关键动作必须同步完成：
- 在 Git 仓库中新建分支（如
v2），从v1最后一个 tag 拉出，避免混入未发布变更 - 修改根目录下
go.mod文件：module github.com/user/lib/v2
- 全局替换所有
import "github.com/user/lib"→import "github.com/user/lib/v2"（包括测试文件和内部子包） - 运行
go mod tidy确保依赖解析正确；再跑go test ./...验证无导入错误 - 打 tag 时严格用
v2.0.0（注意带v前缀），并推送到远程：git tag v2.0.0 && git push origin v2.0.0
为什么 Go 不自动处理路径后缀？
这不是偷懒，而是设计取舍：强制显式声明路径，把兼容性决策权交还给开发者。自动推导会掩盖破坏性变更，比如某次 “小升级” 实际删了关键函数，却因路径未变被下游静默接受，引发线上故障。
立即学习“go语言免费学习笔记（深入）”；
最容易被忽略的一点：**replace 指令不能绕过路径规则**。即使你在自己的 go.mod 里写 replace github.com/user/lib => ./lib-v2，只要 ./lib-v2/go.mod 里还是 module github.com/user/lib，导入时仍会失败——路径不匹配，Go 根本不会尝试加载。
