macOS 安装

macOS 桌面端的依赖由三部分组成：Electron 运行时、SDK 包（@ni-paas-im/electron@0.1.0，当前仅本地 file:）与打包工具链（electron-builder）。三者版本需成组升级。

包名以实际 npm 包为准
@ni-paas-im/electron-macos 不存在（npm 404）。SDK 包名是 @ni-paas-im/electron，当前版本 0.1.0；未发布时从仓库的 sdk/electron 用 file: 本地安装。

npm 安装​

Shell
# 当前仅支持本地 file: 安装（@ni-paas-im/electron@0.1.0 尚未发布到 npm，远程命令会 404）
npm install @ni-paas-im/electron@file:../sdk/electron electron@35
npm install -D electron-builder@24

# 判定 Electron 二进制是否可用（失败见下方兜底）
test -x node_modules/electron/dist/Electron.app/Contents/MacOS/Electron && npx electron --version
Electron 二进制安装兜底

npm 11 / Node 26 可能拦截 electron 的 postinstall；node node_modules/electron/install.js 可能 exit 0 但 dist/ 仍无 Electron.app，只删目录重装也无效。

必须手工解压缓存 zip 并写 path.txt；完整命令见 构建页「Electron 二进制修复」。优先使用 Node 22 LTS + npm 10。

安装后包内提供以下入口；不要跨进程 import 其它入口的实现。

入口导入方式运行位置
主进程服务@ni-paas-im/electron/mainElectron 主进程：initService / IMElectronClient
IPC 注册@ni-paas-im/electron/main/ipcElectron 主进程：registerIpc
preload 桥@ni-paas-im/electron/preloadpreload 脚本：暴露 window.niPaasIMBridge
renderer 代理@ni-paas-im/electron/renderer渲染进程（可选）：直接调 bridge 的薄封装
类型声明@ni-paas-im/electron/types/index.d.ts构建期 TypeScript

package.json 示例​

JSON
{
  "name": "my-desktop-app",
  "version": "0.1.0",
  "type": "module",
  "main": "main.mjs",
  "scripts": {
    "start": "electron .",
    "dist": "electron-builder --mac --x64 --arm64",
    "dist:universal": "electron-builder --mac --universal",
    "sign:adhoc": "codesign --force --deep --sign - \"dist/mac/My App.app\""
  },
  "dependencies": {
    "@ni-paas-im/electron": "file:../sdk/electron"
  },
  "devDependencies": {
    "electron": "35.0.1",
    "electron-builder": "^24.13.3"
  },
  "engines": {
    "node": ">=22.5.0"
  }
}

离线 / 内网安装​

  • 私有 registry：`npm config set registry <内网 registry>` 后再安装。
  • 内网 tarball：`npm pack` 打出 `ni-paas-im-electron-0.1.0.tgz` 后 `npm install ./ni-paas-im-electron-0.1.0.tgz`。
  • Electron 二进制下载慢或被墙：设置 `ELECTRON_MIRROR` 后重新执行 `node node_modules/electron/install.js`；若 `dist/` 仍为空，删除 `node_modules/electron` 重装（见「构建」页排障）。

版本兼容​

组件版本说明
@ni-paas-im/electron0.1.0与 IDL v1 的 103 个语义操作对齐
electron35.x桌面端验证版本（peerDependency >=28）；升级大版本需回归 preload 安全设置
electron-builder24.x打包 / 签名 / 公证编排
Node.js22.5+构建脚本与主进程运行时基线
不要混用入口

主进程与 preload 必须来自同一份 SDK 版本；preload 使用 SDK 自带文件，不要另写一套 `ipcMain.handle` / `ipcRenderer.invoke` 通道。