使用ipc进行通讯

Electron 使用 IPC 进行进程间通讯

Electron 的每个窗口都是一个独立的渲染进程,默认没有 Node.js 能力;系统级操作(文件、对话框、菜单、原生 API)只能由主进程完成。因此 IPC 不是可选的优化手段,而是安全模型推导出的必然结果:渲染进程想做事,必须显式委托主进程。

环境 角色 能力
主进程 main 全局唯一,Node.js 环境 创建 BrowserWindow、app、dialog、Menu、文件系统、原生 API
渲染进程 renderer 每个窗口一个,Chromium 只跑页面 DOM,默认没有 Node 能力
预加载 preload 挂在渲染进程里、运行在隔离世界 可用部分 Node 与 electron 模块,是唯一的桥梁
// preload / renderer
ipcRenderer.send('log:write', 'hello')
 
// main
ipcMain.on('log:write', (event, msg) => { /* ... */ })

拿不到返回值,只适合“通知一下”的场景。

// main
ipcMain.handle('dialog:openFile', async (event, options) => {
  const { canceled, filePaths } = await dialog.showOpenDialog(options)
  return canceled ? null : filePaths[0]
})
 
// preload
const file = await ipcRenderer.invoke('dialog:openFile', { properties: ['openFile'] })

返回 Promise,天然支持 async/await,错误能自动 reject 回去,可读性最好。新代码优先用它。

// main
win.webContents.send('download:progress', { percent: 42 })
 
// preload
ipcRenderer.on('download:progress', (event, data) => callback(data))

方向是反的,必须先注册监听。注意消息可能被错过:如果推送发生在页面注册 on 之前就丢了。

通过 event.returnValue 回传结果,会阻塞渲染进程直到主进程返回。主进程一旦忙、或反过来在等渲染进程,就会死锁。仅用于老 API 兼容。

没有直连通道。要么经主进程转发(用 event.sender 定位来源,再用目标窗口的 webContents.send),要么用 MessageChannelMain / MessagePort 建点对点通道。

现代 Electron 的默认值已经是安全配置(contextIsolation: true、nodeIntegration: false),正确姿势是:

// preload.js
const { contextBridge, ipcRenderer } = require('electron')
 
contextBridge.exposeInMainWorld('api', {
  openFile: (opts) => ipcRenderer.invoke('dialog:openFile', opts),
  onProgress: (cb) => {
    const handler = (_e, data) => cb(data)
    ipcRenderer.on('download:progress', handler)
    return () => ipcRenderer.off('download:progress', handler) // 返回取消订阅
  }
})

三个关键点:

  • 不要把整个 ipcRenderer 暴露出去(例如 exposeInMainWorld('ipc', ipcRenderer))。那样页面能向任意 channel 发消息,主进程的所有 handler 都成了公开接口,等于校验白做。
  • 只暴露“动词”级的窄接口,channel 名写死在 preload 里,页面传不了任意 channel。
  • 页面侧的事件监听必须能解除,所以 onProgress 返回取消函数;否则组件反复挂载卸载会泄漏监听器,最后报 MaxListenersExceededWarning。

另外 ipcMain.handle 里务必校验来源与参数:

ipcMain.handle('fs:read', (event, p) => {
  const url = event.senderFrame?.url ?? ''
  if (!url.startsWith('file://') && !url.startsWith('http://localhost:5173')) {
    throw new Error('untrusted sender')
  }
  // 还要自己校验 p(白名单 / 路径规范化),不要直接丢给 fs
})

参数走结构化克隆(structured clone),不是 JSON:

可以传 不能传
string / number / boolean / null 函数
Array、普通 Object DOM 节点
Date、Map、Set Symbol
ArrayBuffer、TypedArray 类实例的原型(会被克隆成丢掉方法的普通对象)
Error —

错误传播的坑:主进程 throw 的异常到渲染侧只保留 message,并被包装成 Error invoking remote method 'xxx': …,自定义字段和 error.code 都会丢。需要结构化错误时,改成返回结果对象:

return { ok: false, code: 'ENOENT', message: '文件不存在' }

性能:每次 IPC 都有序列化成本,几百 KB 以上的数据(大 JSON、图片 base64)会明显卡界面。可选方案:分批推送、写本地文件后传路径、ArrayBuffer 转移所有权、MessagePort。

  • invoke 找不到 handler → No handler registered for 'xxx'。检查 channel 拼写、handler 是否在窗口创建前注册。
  • 同一 channel 用 handle 重复注册会直接抛错;热重载前先 ipcMain.removeHandler(name)。
  • 窗口已销毁还 send → Object has been destroyed。用 if (win && !win.isDestroyed()) 保护。
  • 弹dialog 时用 BrowserWindow.fromWebContents(event.sender) 当父窗口,否则对话框会脱离窗口,macOS 上可能直接不弹。
  • @electron/remote 已废弃,别用——它就是“把主进程能力塞进渲染进程”的反面教材。
  • preload 里别写业务逻辑,只做转发和形状约束;sandbox: true 时 preload 只能 require electron、events、timers、url。
  • channel 统一命名 模块:动作(dialog:openFile、download:progress),便于检索、避免冲突。
  • 主→渲染的推送要处理“错过”问题:要么页面启动时主动 invoke 拉一次初始状态,要么主进程缓存最后一次值。
用 ''invoke/handle'' 做主流程,''webContents.send'' 做推送,所有跨进程能力都通过 ''contextBridge'' 暴露最小接口,并且**永远不信任来自渲染进程的参数**。
# Electron IPC 进程间通讯

## 进程模型
### 主进程 main
- 全局唯一,Node.js 环境
- 窗口 / 菜单 / 对话框 / 文件系统
### 渲染进程 renderer
- 每窗口一个,Chromium
- 默认没有 Node 能力
### 预加载 preload
- 隔离世界
- 唯一桥梁

## 四条通道
### 渲染 → 主 send / on
- 单向通知
- 拿不到返回值
### 渲染 → 主 invoke / handle(首选)
- 返回 Promise
- 支持 async/await
- 错误自动 reject
### 主 → 渲染 webContents.send
- 先注册 ipcRenderer.on
- 小心消息被错过
### 同步 sendSync
- 阻塞渲染进程
- 有死锁风险,避免
### 渲染 ↔ 渲染
- 经主进程转发
- MessageChannelMain / MessagePort

## 安全
### contextIsolation 默认 true
### nodeIntegration 默认 false
### 不暴露整个 ipcRenderer
### 只暴露动词级窄接口
### channel 名写死在 preload
### 校验 event.senderFrame.url
### 参数自己做白名单

## 传值规则
### 结构化克隆,不是 JSON
- Date / Map / Set / ArrayBuffer
### 不能传函数、DOM、Symbol
### 类实例会丢原型方法
### Error 只保留 message
- 建议返回 { ok, code }
### 大数据要分批或走文件

## 常见坑
### No handler registered
### handle 重复注册会抛错
### Object has been destroyed
### 监听器泄漏 MaxListenersExceeded
### dialog 父窗口 fromWebContents
### sandbox 下 preload 受限
### channel 命名 模块:动作

## 一句话
### invoke/handle 做主流程
### webContents.send 做推送
### 最小暴露
### 永不信任渲染进程参数

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • 使用ipc进行通讯.txt
  • 最后更改: 2026/11/17 08:16
  • 由 张叶安