macOS 分发与自动更新

口径说明

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

分发环节决定用户能否“下载 → 拖入 Applications → 双击可用”。macOS 推荐分发已签名并公证的 `.dmg`；自动更新按需接入，更新包同样需要签名与公证。

分发产物​

产物用途要求
`--x64.dmg`Intel Mac 下载签名 + 公证 + stapling
`--arm64.dmg`Apple Silicon 下载签名 + 公证 + stapling
`--universal.dmg`单包覆盖两种架构体积大；签名 + 公证 + stapling
`latest-mac.yml`自动更新元数据（按需）版本、文件地址、sha512
`*.dSYM`崩溃符号化归档，不随用户分发

发布检查清单​

  1. 版本号与 `package.json` / `Info.plist` 一致（`CFBundleShortVersionString`、`CFBundleVersion`）。
  2. `.app` 已用 Developer ID 签名并开启 hardened runtime。
  3. `.app` 与 `.dmg` 均已公证并 stapling（`spctl` 显示 accepted）。
  4. 在干净机器（未安装任何开发证书）上验证：下载 → 挂载 → 拖入 Applications → 双击启动 → 登录收发。
  5. 生成 SHA-256 校验值并随下载页公布。
  6. 归档构建日志、签名证书指纹、公证 submission id 与 dSYM。
Shell
shasum -a 256 "dist/My Desktop-0.1.0-arm64.dmg"
# 输出示例：9f2c...  dist/My Desktop-0.1.0-arm64.dmg

自动更新（按需接入）​

桌面端可在主进程接入 electron-updater：启动后检查更新源，发现新版本时下载签名包并在下次启动安装。更新源可以是静态文件服务器（`latest-mac.yml` + dmg）或对象存储；关键是更新包与主包使用同一张 Developer ID 证书签名。

JavaScript
// main.mjs：按需启用自动更新（示例使用 electron-updater）
import { autoUpdater } from 'electron-updater';

autoUpdater.autoDownload = true;
autoUpdater.autoInstallOnAppQuit = true;

autoUpdater.on('update-available', (info) => broadcast('im:update-available', info));
autoUpdater.on('update-downloaded', (info) => broadcast('im:update-ready', info));

app.whenReady().then(() => {
  // 仅打包后的应用检查更新；开发态跳过
  if (app.isPackaged) autoUpdater.checkForUpdatesAndNotify();
});
自动更新的安全前提

更新包必须由同一 Developer ID 证书签名并通过公证，否则安装会被系统拒绝。

更新源需支持 HTTPS 与断点续传；`latest-mac.yml` 中的 sha512 必须与实际文件一致。

重大版本升级前建议在应用内提示备份本地库，并保留回滚到上一版本的下载入口。

灰度与回滚​

策略做法
分批放量更新源按渠道（stable / beta）分目录，客户端按配置选择渠道
强制升级服务端下发最低支持版本，客户端低于时阻断登录并引导下载
回滚保留上一版本 dmg 与更新元数据；把 `latest-mac.yml` 指向旧版本即可
崩溃监控接入崩溃上报并把 dSYM 上传到符号服务器