主版本升级必须改import路径，Go将v1和v2视为完全独立模块；不改路径会导致“cannot find package”或undefined错误，replace无法自动重写import语句，需同步更新go.mod、所有import语句及调用代码。
主版本升级必须改 import 路径
Go 把 v1 和 v2 视为完全不同的模块，不是“新版替代旧版”，而是“两个独立包”。如果你直接把 github.com/some/lib 升到 v2.0.0，但代码里还写 import "github.com/some/lib"，编译器根本找不到 v2 的代码——它只认 github.com/some/lib/v2。
常见错误现象：cannot find package "github.com/some/lib" in any of... 或者更隐蔽的：undefined: somefunc（因为 v2 里函数名/签名已变，但你仍按 v1 的 import 引入）。
- 正确做法是：先改
go.mod中的require行为github.com/some/lib/v2 v2.0.0 - 再全局替换所有
import "github.com/some/lib"→import "github.com/some/lib/v2" - 接着逐个修复调用点：v2 可能删了旧方法、重命名了类型、或改了参数顺序——不能靠
go mod tidy自动修
replace 无法绕过 v2 路径变更
replace 只能映射路径和版本，不能改变 Go 的 import 解析规则。写 replace github.com/some/lib => github.com/some/lib/v2 v2.0.0 是无效的——github.com/some/lib 和 github.com/some/lib/v2 在 Go 看来是两个不同路径，replace 不会自动重写 import 语句。
容易踩的坑：
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 误以为加了 replace 就能“无缝升级”，结果编译失败且报错指向 import 行
- 在本地用 replace 指向
./lib-v2，但该目录下go.mod声明的是module github.com/some/lib/v2，而主项目 import 的仍是github.com/some/lib，路径不匹配 - CI 构建时因 GOPROXY 缓存旧版本，replace 生效但实际拉取的仍是 v1 的校验和，导致
go mod verify失败
如何安全过渡 v1 到 v2
不要一次性全量切换。尤其当项目同时被多个服务或 SDK 依赖时，v1 用户可能还没准备好升级。
实操建议：
- 保留 v1 分支继续维护 bugfix，新功能全在 v2 分支开发
- 如果必须共存（比如一个 binary 同时用 v1 和 v2），确保它们 import 路径完全不同，Go 允许这种并存——
v1和v2是隔离的 - 用
go list -m all | grep some/lib确认最终加载的是哪个路径，而不是只看版本号 - 测试时重点覆盖接口实现类：v2 常重构 interface 方法签名，mock 实现若没同步更新，
go test会 panic 而非编译报错
伪版本 + replace 适合临时验证，但不等于兼容
当你想快速验证某个未发版的 v2 分支是否可用，可以用伪版本 + replace：
replace github.com/some/lib/v2 => github.com/some/lib v0.0.0-20260720153000-abcdef123456
但要注意：
- 这个 commit 必须已发布到
github.com/some/lib主仓库，且其go.mod中声明的是module github.com/some/lib/v2 - 伪版本本身不解决 API 不兼容问题——它只是让你提前试用，所有 breaking change 仍需手动适配
- 上线前必须移除 replace，改用正式 tag，并提交
go.sum更新；否则 CI 可能因校验和不一致失败
最常被忽略的一点：v2 的破坏性更新往往藏在文档变更里，而不是编译错误中。比如日志字段格式调整、HTTP 响应头默认值变化、或 context deadline 行为微调——这些不会让 go build 失败，但会让集成测试或线上监控突然异常。
