macOS 升级与兼容

口径说明

融云公开文档不覆盖 macOS 原生 SDK 与桌面交付链（dmg / 代码签名 / 公证 / 分发 / Gatekeeper）；本页为本项目按 Apple 与 Electron 官方实践补齐的接入文档。

桌面端升级涉及三层：SDK（语义面）、Electron 运行时（安全与系统能力）、本地库（数据结构）。三者需要成组验证，避免只升 SDK 导致 preload 或数据库迁移失败。

升级矩阵​

升级对象兼容策略回归重点
SDK 1.0.x → 1.xIDL additive-only：仅新增可选字段 / 枚举值 / 操作连接、收发、会话、本地库迁移
Electron 35 → 36+跟随官方 breaking changes；preload 安全默认值可能变化contextBridge、sandbox、Frameworks 签名
electron-builder 24 → 25+打包配置字段可能更名mac target、entitlements、公证参数
macOS 最低版本上调影响用户覆盖发布说明中标注，必要时做版本检测与提示

升级步骤​

  1. 备份本地库（见「本地 SQLite」页），记录当前版本号。
  2. 升级依赖并执行 `npm ci`，确认 Electron 二进制与架构正确。
  3. 启动开发态，验证连接、收发、历史、会话列表、未读与草稿。
  4. 执行一次冷启动（退出后重开），确认本地库迁移成功且历史仍在。
  5. 打包 → 签名 → 公证 → 在干净机器验证首次启动。
  6. 灰度发布，观察崩溃与连接失败率，再全量。

本地库迁移失败的回滚​

Shell
# 1) 退出应用
osascript -e 'quit app "My Desktop"'

# 2) 备份当前库
cp -R "$HOME/Library/Application Support/My Desktop" ~/Desktop/im-db-backup

# 3) 回滚到上一版本应用，恢复旧库后启动
open "/Applications/My Desktop.app"
版本能力检测

对于新增的语义操作，客户端应先判断当前 SDK 是否支持（能力探测 / 版本号），不支持时降级 UI，而不是直接调用导致错误码。