iOS 升级与兼容
iOS SDK 的版本策略是 additive-only：只新增可选字段、枚举值与操作，不破坏既有语义。升级时按“契约变更 → 依赖升级 → 回归主链路 → 发版”的顺序执行。
升级步骤
- 阅读更新日志，确认新增 / 变更的语义操作与错误码。
- 按集成方式升级依赖（CocoaPods `pod update` / SPM 更新版本 / 替换 XCFramework）。
- 清理构建缓存（`DerivedData`）后全量编译，确认无符号冲突。
- 回归主链路：初始化 → 连接 → 收发文本 / 图片 → 会话列表 → 历史消息 → 撤回 / 已读。
- 回归 Objective-C 侧：确认 ObjC 声明仍可用（`IMP*` 符号无改名）。
- 更新 App 版本号并发版；灰度观察连接成功率与崩溃率。
兼容矩阵
| 升级项 | 兼容性 | 注意事项 |
|---|---|---|
| 1.0.x → 1.x | 向后兼容（additive-only） | 新增操作可直接使用；旧代码无需改动 |
| Xcode 15 → 16 | 源码兼容 | 重新编译并回归签名 / 归档流程 |
| iOS 最低版本上调 | 影响用户覆盖 | 发布说明标注；旧系统用户停留在上一版本 |
| IMKit 组件扩展 | props / events 只增不改 | 自定义渲染器需检查新增可选属性 |
| Objective-C 声明 | 选择器保持稳定 | 升级后跑一次 ObjC 集成用例 |
常见升级问题
| 现象 | 原因 | 处理 |
|---|---|---|
| `Multiple commands produce ...` | 同时用 CocoaPods 与 SPM 引入同名模块 | 只保留一种集成方式 |
| `Undefined symbols: IMP...` | XCFramework 未 Embed & Sign | Target → General 设为 Embed & Sign |
| 启动崩溃 `dyld: Library not loaded` | Framework 未随包嵌入 | 检查 Embed 阶段与 Runpath Search Paths |
| 收不到离线消息 | 升级后 deviceId / 游标被清 | 重装或清缓存会生成新 deviceId，首次会补收未 ack 消息；确认服务端补发正常 |
| ObjC 编译告警 `@objc` 名称冲突 | 宿主自定义类与 SDK 前缀冲突 | 避免使用 `IMP` 前缀命名自有类 |
回滚
保留上一版本的 Podfile.lock / Package.resolved 与 XCFramework 包；回滚后清理 DerivedData，避免残留旧模块。