Go包API不兼容变更必须升主版本并更新模块路径，如v1→v2且路径变为github.com/user/lib/v2；不兼容变更包括函数签名、返回值、导出字段、接口方法及未文档化行为改动。
Go包的API变更直接触发module主版本升级，这是语义化版本（SemVer）的核心约束。只要出现不兼容的修改——比如函数签名变更、结构体字段删除、方法移除或行为逻辑调整——就必须升主版本（如 v1 → v2），并同步更新模块路径（如 github.com/user/lib → github.com/user/lib/v2）。否则编译会失败，或运行时出现静默错误。
哪些API变更算“不兼容”
不是所有代码改动都会影响兼容性。关键看是否破坏已有调用方的正常使用：
- 函数参数类型或数量变化（如
Do(x int)→Do(x string)） - 返回值类型或个数变更（如从
func Get() int改为func Get() (int, error)） - 导出结构体字段被删、重命名，或类型不兼容（如
ID int→ID string） - 接口方法被移除或签名变更（实现该接口的类型将无法满足新定义）
- 公开函数/方法的行为发生非文档化改变（如原本空输入返回 nil，现在 panic）
如何提前发现API变更影响
升级前别只看版本号，要主动验证实际影响：
- 用
go list -m -u all查出可升级项，再结合go list -m -versions github.com/example/lib看具体有哪些稳定版可选 - 读目标版本的 CHANGELOG 或
UPGRADE.md，重点关注 “Breaking Changes” 和 “Migration Guide” - 运行
go doc github.com/example/lib@v2.0.0对比旧版文档，快速定位导出符号增减 - 在干净分支上执行
go get github.com/example/lib@v2.0.0 && go mod tidy，再跑go test ./...，观察编译错误和测试失败点
主版本升级后的正确导入方式
v2+ 模块不是“升级”，而是“新增一个独立模块”。必须显式使用带版本后缀的路径导入：
- ❌ 错误：仍写
import "github.com/user/lib"（这只会拉 v0/v1） - ✅ 正确：改写为
import "github.com/user/lib/v2"，且go.mod中 require 行也必须含/v2 - 共存没问题：项目里可以同时有
github.com/user/lib（v1）和github.com/user/lib/v2，Go 会分别加载 - 注意：v2 模块内部仍应保持自身语义化版本演进，比如后续发 v2.1.0 不需改路径
临时绕过兼容问题的方法
当升级卡在某个依赖的API变更上，又不能立刻改业务代码，可用以下方式争取时间：
- 用
replace锁定旧版（仅限临时调试）：replace github.com/user/lib => github.com/user/lib v1.9.0 - 若已升级但部分代码还没适配，可分批迁移：保留老 import 路径 + replace 指向兼容分支，新功能用新路径
- 避免长期依赖
replace或 fork 修复，它会让构建不可重现，CI 可能失效
基本上就这些。API变更本身不可怕，可怕的是忽略它的版本含义。盯住 SemVer 规则、看清路径变化、验证导入行为，就能把升级变成一次可控演进。
