go mod tidy 无法自动解决跨 major 版本冲突，需手动清理残留依赖、检查多版本共存、谨慎使用 replace、同步更新子依赖、适配 protobuf 反射层变更、重生成 .pb.go 文件、验证历史数据兼容性并执行原子化迁移。
go mod tidy 无法自动修复的版本冲突
升级 Go 模块时，go mod tidy 只会拉取满足约束的最新兼容版本，但不会主动解决跨 major 版本的不兼容问题。比如 github.com/go-mysql-org/go-mysql 从 v1 到 v2，导入路径必须带 /v2 后缀，否则 Go 仍加载旧版，造成隐式多版本共存。
- 运行
go mod graph | grep go-mysql查看是否实际加载了多个版本 - 检查
go.mod中是否存在未显式声明的indirect依赖，它们可能偷偷引入旧版 - 若发现冲突，用
go mod edit -droprequire=github.com/go-mysql-org/go-mysql@v1.x清理残留引用
replace 指令不是万能解药
replace 能强制统一源码路径，但掩盖了真正的 API 兼容性缺口。例如 RobotGo v2 的 mouse.Move 参数顺序变更，仅靠 replace 无法让旧调用正常工作。
- 替换后必须运行
go build -a（而非默认增量编译），确保所有包重新链接 - 重点检查 CGo 相关模块（如
base/bitmap_free_c.h），v2 新增的FreeBitmap()必须在旧逻辑中显式调用，否则内存泄漏 - 若被 replace 的模块本身依赖其他模块（如
go-mysql依赖golang.org/x/net），需同步确认其子依赖是否也兼容
protobuf-go 迁移中容易忽略的反射层断裂
从 proto.Message 切换到 protoreflect.Message 后，旧代码里直接调用 XXX_Unmarshal 或 XXX_MessageName 会静默失效——编译不报错，但运行时返回空或 panic。
- 搜索全部
.go文件中的XXX_前缀方法，逐个替换为ProtoReflect().Descriptor()...形式 - 特别注意测试用例中硬编码的 proto 文本（
proto.MarshalTextString），新版本需改用prototext.MarshalOptions{} - 生成的
.pb.go文件必须用匹配的protoc-gen-go@latest重生成，旧版生成器产出的代码与新 runtime 不兼容
历史数据格式变更必须配套迁移脚本
模块升级常伴随序列化格式变化（如 Go-MySQL v1.14.0 对 LogPos=0 的处理逻辑变更），旧数据在新版本下可能解析失败或语义错误。
立即学习“go语言免费学习笔记（深入）”；
- 不要依赖“向后兼容”宣传，用真实 binlog 数据跑一遍
replication.BinlogSyncerConfig{FillZeroLogPos: true}验证 - 对关键结构体（如 protobuf 定义的 message）做双写：升级期间同时输出新旧格式，比对字段映射是否丢失
- 数据库 schema 变更（如新增非空字段）必须配原子化迁移脚本，避免服务启动时因
sql.Open失败卡死
