Electron 主进程和渲染进程通信的配置分三步:确定通信方向和通道名,在主进程注册处理函数,再用 preload 把可用方法收窄后挂到 window 上。现在默认开启 contextIsolation,不再建议在渲染进程直接拿到完整的 ipcRenderer;远程过程风格的读写先用 ipcRenderer.invoke 配 ipcMain.handle,主进程主动下发的消息用 webContents.send 配 ipcRenderer.on。渲染窗口保持 nodeIntegration: false,所有文件、系统、网络操作留在主进程执行。
判断方向:渲染进程只声明“我要做什么”,主进程负责校验和执行。操作动作是把通道名以域:动作命名,在 preload 里用contextBridge暴露少量方法,其余能力不对外。验证方式是调用后看返回是否为 Promise、非法入参是否被拒绝、页面里window.require是否仍然为 undefined。边界是 preload 属于受沙箱限制的运行环境,涉及第三方模块或同步阻塞调用时,需要结合本地 Electron 版本重新评估。
先确认当前场景和目标
在动手接线之前,先确认三件事;否则很容易写出“能跑但不好维护”的版本。
- 通信方向:只有渲染进程发起请求,用
invoke/handle就够了;主进程要主动推状态、推进度,就必须额外准备send/on通道;如果需要双向持续对话(例如长任务中途取消),把“取消”也做成一个独立通道,并不要复用同一个通道。 - 窗口范围:单窗口可以直接在创建窗口时拿到
win;多窗口时必须用event.sender定向回复,不能对全部窗口广播。 - 安全基线:
contextIsolation是否被历史代码关掉、sandbox是否开启、是否还残留nodeIntegration: true。这三项决定了 preload 里能写什么,需要结合项目当前的 Electron 版本确认。
如果项目里已经有旧的 ipcRenderer.sendSync 或全局 remote 用法,先把它们列出来,在本次改造中一并处理;如果只改新增功能,新旧两套通道会长期并存。
按这个顺序处理
建议按“主进程注册 → preload 暴露 → 渲染进程调用”的顺序改,每一步都能单独验证。下面三块代码可以直接替换项目里的同名文件;通道名、参数名都是示意,替换成你自己的业务名即可。
第一步,在主进程里注册处理函数。这里同时演示请求响应和主动推送两种方向。注意入参校验要在主进程做,渲染进程传来的任何值都当作不可信输入。

// main.js
const { app, BrowserWindow, ipcMain } = require('electron');
const path = require('node:path');
function createWindow() {
const win = new BrowserWindow({
width: 1000,
height: 700,
webPreferences: {
preload: path.join(__dirname, 'preload.js'),
contextIsolation: true, // 保持默认开启
nodeIntegration: false, // 渲染进程不直接拿 Node
sandbox: true // 如需在 preload 里 require 第三方模块,再单独评估
}
});
win.loadFile('index.html');
return win;
}
// 渲染进程 → 主进程:一问一答
ipcMain.handle('config:read', async (event, options) => {
const name = options && options.name;
if (typeof name !== 'string' || name.includes('..')) {
throw new Error('config:read 参数不合法');
}
// 真正读文件、查数据库的动作放在这里
return { name, content: '示例内容' };
});
app.whenReady().then(() => {
const win = createWindow();
// 主进程 → 渲染进程:定向推送,避免广播到所有窗口
win.webContents.send('app:status', { ready: true });
});
第二步,在 preload 里用 contextBridge 暴露收窄后的接口。这里不要直接暴露 ipcRenderer 对象,也不要写“传入通道名由页面自己拼”的通用转发函数,否则任何脚本都能调用任意通道。
// preload.js
const { contextBridge, ipcRenderer } = require('electron');
contextBridge.exposeInMainWorld('bridge', {
readConfig: (options) => ipcRenderer.invoke('config:read', options),
// 订阅型接口必须返回取消函数,避免页面切换后监听器堆积
onStatus: (handler) => {
const listener = (_event, payload) => handler(payload);
ipcRenderer.on('app:status', listener);
return () => ipcRenderer.removeListener('app:status', listener);
}
});
第三步,在渲染进程里调用。渲染层只看到 window.bridge,拿不到 Node 能力;失败分支也要写,主进程抛出的错误会以 reject 形式回到这里。
// renderer.js
async function init() {
try {
const cfg = await window.bridge.readConfig({ name: 'app.json' });
console.log(cfg.content);
} catch (err) {
console.error('读取配置失败:', err.message);
}
const off = window.bridge.onStatus((status) => {
console.log('主进程状态:', status);
});
window.addEventListener('beforeunload', off);
}
init();
改完后怎么验证
验证分两层:先确认能力边界还在,再确认通道真的通了。
- 打开开发者工具的 Console,执行
typeof window.require,预期返回undefined;执行typeof window.bridge.readConfig,预期返回function。如果第一个不是 undefined,说明隔离配置没有生效,先回头检查webPreferences。 - 在页面里调用一次正常请求,观察返回值是否是 Promise 结果而不是 undefined。主进程一侧可以临时加一行日志,确认处理函数确实被触发了一次,并且只被触发一次。
- 故意传入非法参数(例如带
..的路径或非字符串),确认页面拿到的是 reject,并且错误信息能显示出来,并且主进程没有崩溃。 - 测试主进程推送:触发一次
webContents.send,确认页面收到消息;再重复切换页面或重新挂载组件几次,观察监听器是否会叠加。判断依据是同一事件只打印一次。如果叠加,说明取消函数没有被调用。 - 打包后再跑一遍上述步骤。开发态正常、打包后失效是常见情况,原因通常落在 preload 路径、asar 内路径解析或沙箱限制上,需要结合构建配置确认。
多窗口场景再补一条:从 A 窗口发起请求,确认只有 A 窗口收到回复,不会串到 B 窗口。这一点用 event.sender 回复就能避免,验证时直接把两个窗口并排观察即可。
容易忽略的边界
版本与模块格式:contextIsolation 在新版本里是默认开启的,但老项目可能显式关掉过;如果 package.json 里写了 "type": "module",CommonJS 写法的 preload 可能加载失败,需要改成 .cjs,或者确认当前版本是否支持 ESM preload。这一条必须对照本地实际版本,不能照搬别人的写法。

沙箱限制:sandbox: true 时 preload 能用的模块很有限,通常只能拿到 electron 的少量接口和部分内置模块。如果业务确实要在 preload 里引第三方库,可以先尝试把逻辑挪回主进程,通过通道把结果传回页面,往往比关沙箱更省事。
数据序列化:跨进程传参走结构化克隆,普通对象、数组、Date、Map 一般可用,函数、类实例、DOM 节点传不过去,会报错或变成空对象。大体积的二进制数据建议先落到临时文件或返回可寻址的标识,不要在通道里整体搬运。
同步调用与监听泄漏:sendSync 会阻塞渲染进程,除极少数初始化场景外不建议使用;ipcRenderer.on 注册后必须配对移除,否则热更新和页面切换时会出现重复响应。
不适用与回退:如果当前项目仍然依赖 nodeIntegration: true 且短期内无法改,可以先只对新功能使用 preload 通道,把旧代码圈定在独立窗口里,先不一次性全改;如果 preload 方案在某些平台上加载异常,回退做法是把该能力做成主进程侧的命令式接口,由页面通过既有的请求通道触发,先不追求双向推送。