macOS 排障手册
口径说明
融云公开文档不覆盖 macOS 原生 SDK 与桌面交付链（dmg / 代码签名 / 公证 / 分发 / Gatekeeper）；本页为本项目按 Apple 与 Electron 官方实践补齐的接入文档。
本页覆盖桌面端特有的故障：架构不匹配、原生模块加载失败、preload 未生效、白屏、连接失败与本地库异常。签名 / 公证 / Gatekeeper 问题见对应页面。
故障速查
| 现象 | 常见原因 | 处理 |
|---|---|---|
| `mach-o, but wrong architecture` | x64 / arm64 二进制混用（Rosetta 未装或包架构不对） | 用 `lipo -info` 确认主程序与依赖架构；重装对应架构的包 |
| `dlopen ... no such file` / `cannot open shared object` | 原生依赖缺失或路径未打包进 asar | 检查 `files` / `extraResources`；必要时把原生依赖解包到 `app.asar.unpacked` |
| 白屏 / 页面脚本未执行 | `loadFile` 路径错误、CSP 拦截、preload 抛错 | 打开 DevTools（`win.webContents.openDevTools()`）看控制台与 preload 错误 |
| `window.niPaasIMBridge is undefined` | preload 未加载 / `sandbox:true` 导致 ESM preload 未执行 / preload 路径错误 | 确认 `webPreferences.preload` 指向 SDK preload 绝对路径、`sandbox:false`、`contextIsolation:true` |
| 连接一直失败（1002/3001/3002） | Token 无效 / 服务端地址不可达 / 代理拦截 WebSocket | `1002` 重新登录；`3001/3002` 检查网络与服务端地址；抓包确认 Upgrade 头 |
| 本地历史为空 | dbPath 变更 / 迁移失败 / 首次登录 | 检查用户数据目录；查看主进程日志中的迁移错误 |
| 打包后功能正常但通知不弹 | 通知权限未授予 / 应用未签名 | 系统设置开启通知；发布包完成签名与公证 |
| `Error: Cannot find module 'electron'` | 依赖未安装或被打包排除 | `npm ci`；确认 `files` 包含主进程依赖 |
日志与调试
Shell
# 主进程日志
ELECTRON_ENABLE_LOGGING=1 npx electron . 2>&1 | tee /tmp/im-desktop.log
# 渲染进程：打开 DevTools（主进程调用）
# mainWindow.webContents.openDevTools({ mode: 'detach' })
# 系统日志（崩溃 / 权限 / 通知）
log show --last 10m --predicate 'process == "My Desktop"' --info
# 包架构
lipo -info "dist/mac/My Desktop.app/Contents/MacOS/My Desktop"
file "dist/mac/My Desktop.app/Contents/MacOS/My Desktop"本地库异常
| 现象 | 处理 |
|---|---|
| 启动时报库版本不匹配 | 备份 `im.db*` 后删除本地库，重新登录补收（会丢失本地缓存） |
| 库文件损坏（disk I/O error） | 退出应用，用备份恢复；无备份则删除重建 |
| 迁移卡住 / 一直 loading | 查看主进程日志；保留旧库并回滚到上一版本应用 |
| 多进程同时打开库 | 确认只有一个主进程实例（`requestSingleInstanceLock`），不要在渲染进程直连库 |
相关：Gatekeeper 排障、本地 SQLite、架构、错误码。