主版本升级必须改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.0 tag 会被忽略，或触发 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 不自动处理路径后缀？

这不是偷懒，而是设计取舍：强制显式声明路径，把兼容性决策权交还给开发者。自动推导会掩盖破坏性变更，比如某次 “小升级” 实际删了关键函数，却因路径未变被下游静默接受，引发线上故障。

最容易被忽略的一点：**replace 指令不能绕过路径规则**。即使你在自己的 go.mod 里写 replace github.com/user/lib => ./lib-v2，只要 ./lib-v2/go.mod 里还是 module github.com/user/lib，导入时仍会失败——路径不匹配，Go 根本不会尝试加载。