第一个现场:页面要读一个本地日志文件。同事在 main.js 里打开 nodeIntegration: true,页面上写一行 const fs = require('fs'),文件内容立刻读出来了,大家觉得 Electron 真方便。半年后安全扫描提了整改,要求关掉 Node 集成、打开上下文隔离和沙箱。改完配置,页面里所有 require 全部报错,读文件、导出、调用打印机一起挂掉。于是有人提议「要不还是把 nodeIntegration 打开吧」。
第二个现场:一个带下载功能的后台,每个页面组件在挂载时都写一句 ipcRenderer.on('download:progress', ...),卸载时没有对应的移除。用户在「任务列表」「任务详情」「设置」之间来回切换,监听器一层层叠上去。切到第五个页面,事件回调被触发五次,四次在更新已经不在屏幕上的组件;再切几次,开始出现「对象已被销毁」的报错,内存也一路往上走。
这两个现场指向同一件事:预加载脚本和进程间通信不是「能调通就行」的胶水,它是一条明确的安全边界和资源边界。桥开多大、参数怎么校验、来源怎么确认、监听器谁来清理,决定了这个桌面程序是「能用」还是「能交付」。
这篇先讲两条通道分别适合什么,再用一个「选择文件并读取内容」的三文件示例把请求、校验、返回、错误处理串起来,最后讲监听器泄漏、同步调用卡死、沙箱里为什么不能直接用 fs。版本说明:本机装的是 Electron 45.2.3,但进程启动即崩(0xC0000005,加 --no-sandbox --disable-gpu 也一样),所以三个文件的示例没有在运行时跑通,contextBridge 与 IPC 的调用结果按公开 API 描述;示例的前提仍是 contextIsolation: true、sandbox: true、nodeIntegration: false。
两条通道:要结果用 invoke,要通知用事件
Electron 的 IPC 不是「一个万能函数」,它至少有两种形态,各自对应不同的交互模式。
ipcRenderer.invoke 发一个通道名和参数,主进程用 ipcMain.handle 注册处理函数,返回值会变成 Promise 的结果。适合「读文件」「保存配置」「弹对话框」这类一次性、需要结果的调用。send 发给主进程,主进程用 webContents.send 发给某个窗口,接收方用 on 订阅。没有返回值,适合进度、日志、状态变化、菜单命令这类「发生了就通知」的场景。contextBridge.exposeInMainWorld 把上面两类能力包装成有名字的对象,挂在页面的 window 上。页面只能看到你显式暴露的方法,看不到 ipcRenderer 本身。选择哪种,看调用方需不需要等结果。需要结果却用 send,就得自己再造一套「请求 id 加回调」的协议,等于把 invoke 重新实现一遍;反过来,只是通知「下载完成」,用 invoke 会让主进程多写一个没有意义的返回值。规则很简单:一次性、有结果、可能失败,用 invoke;持续、广播、不需要确认,用事件。
ipcMain.handle 对同一个通道只能注册一个处理函数,重复注册会直接抛「Attempted to register a second handler」;而 ipcMain.on 可以挂多个监听器,这一点和 Node 的 EventEmitter 一样。ipcRenderer.invoke 返回的是 Promise,处理函数里抛出的异常会变成 Promise 的 reject;send 则没有这个反馈通道,主进程出错时渲染进程完全不知道。
最后一个原则:不要把整个 ipcRenderer 暴露给页面,也不要暴露一个「传通道名和参数就能调用任意通道」的通用函数。那等于把 IPC 的全部能力开放给页面,桥就失去了意义。正确做法是一个能力一个方法,名字写死,参数在主进程再校验一遍。
场景走查:选择文件并读取内容
需求:页面上一个按钮,点击后弹出系统文件选择框,只允许选文本类文件;选中后读取内容,页面上显示文件路径和正文前一部分;用户取消时给出提示;文件超过 1MB 时不读,直接说明原因;读取失败不能让页面崩掉。所有文件操作都在主进程,页面只调用一个方法。
目录和依赖与上一篇一样:
mkdir electron-files
cd electron-files
npm init -y
npm i -D electron
package.json 只需要保证 main 指向 main.js,scripts.start 是 electron .。接下来是三个文件。第一个,主进程 main.js:创建窗口、注册通道、校验来源、限制大小、把错误转成可读的结果。
const { app, BrowserWindow, dialog, ipcMain } = require('electron');
const fs = require('node:fs/promises');
const path = require('node:path');
const { pathToFileURL } = require('node:url');
const PAGE_URL = pathToFileURL(path.join(__dirname, 'index.html')).href;
const MAX_BYTES = 1024 * 1024;
let mainWindow = null;
function createWindow() {
const win = new BrowserWindow({
width: 900,
height: 640,
show: false,
webPreferences: {
preload: path.join(__dirname, 'preload.js'),
contextIsolation: true,
nodeIntegration: false,
sandbox: true
}
});
mainWindow = win;
win.once('ready-to-show', () => win.show());
win.loadFile(path.join(__dirname, 'index.html'));
win.on('closed', () => { mainWindow = null; });
}
function assertTrustedSender(event) {
if (!mainWindow || event.sender !== mainWindow.webContents) {
throw new Error('来源窗口不被允许');
}
const frameUrl = event.senderFrame?.url.split('#')[0];
if (frameUrl !== PAGE_URL) {
throw new Error('来源页面不被允许');
}
}
ipcMain.handle('file:pick-and-read', async (event) => {
assertTrustedSender(event);
const win = BrowserWindow.fromWebContents(event.sender);
const result = await dialog.showOpenDialog(win, {
title: '选择要读取的文本文件',
properties: ['openFile'],
filters: [{ name: '文本文件', extensions: ['txt', 'md', 'log'] }]
});
if (result.canceled || result.filePaths.length === 0) {
return { ok: false, code: 'CANCELED' };
}
const filePath = result.filePaths[0];
try {
const stats = await fs.stat(filePath);
if (stats.size > MAX_BYTES) {
return { ok: false, code: 'TOO_LARGE', message: '文件超过 1MB' };
}
const text = await fs.readFile(filePath, 'utf8');
return { ok: true, path: filePath, text };
} catch (error) {
console.error('读取文件失败', filePath, error);
return { ok: false, code: 'READ_FAILED', message: '读取失败,请查看主进程日志' };
}
});
app.whenReady().then(() => {
createWindow();
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) createWindow();
});
});
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') app.quit();
});
第二个文件,预加载脚本 preload.js。它只暴露一个方法,不传通道名,不允许页面自己拼参数:
const { contextBridge, ipcRenderer } = require('electron');
contextBridge.exposeInMainWorld('files', {
pickAndRead: () => ipcRenderer.invoke('file:pick-and-read')
});
第三个文件,页面 index.html,里面内联一段脚本。注意按钮在等待期间要禁用,避免用户连点几次弹出多个对话框;错误分支要覆盖「取消」「业务失败」「调用异常」三种。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>文件读取演示</title>
<style>
body { font-family: system-ui, sans-serif; padding: 32px; }
#output { white-space: pre-wrap; background: #f3f4f6; padding: 12px; }
</style>
</head>
<body>
<h1>文件读取演示</h1>
<button id="pick" type="button">选择文件并读取</button>
<p id="status">尚未选择文件</p>
<pre id="output"></pre>
<script>
const button = document.getElementById('pick');
const status = document.getElementById('status');
const output = document.getElementById('output');
button.addEventListener('click', async () => {
button.disabled = true;
status.textContent = '正在等待选择…';
output.textContent = '';
try {
const result = await window.files.pickAndRead();
if (!result.ok && result.code === 'CANCELED') {
status.textContent = '已取消';
return;
}
if (!result.ok) {
status.textContent = `失败:${result.message}(${result.code})`;
return;
}
status.textContent = `已读取:${result.path}`;
output.textContent = result.text.slice(0, 2000);
} catch (error) {
status.textContent = `调用失败:${error.message}`;
} finally {
button.disabled = false;
}
});
</script>
</body>
</html>
启动 npm start。预期结果:窗口打开,页面显示一个按钮和「尚未选择文件」;点按钮弹出系统文件选择框,过滤器只有文本类扩展名;选中一个几 KB 的 txt,状态变成「已读取:完整路径」,下方显示正文前 2000 个字符;点取消,状态显示「已取消」;选一个超过 1MB 的日志,状态显示「失败:文件超过 1MB(TOO_LARGE)」,页面不崩。打开 DevTools,输入 window.require 应当是 undefined,输入 window.files 只能看到 pickAndRead 一个方法。以上为预期行为,本机未安装 Electron,未实际运行。
这个例子里,页面从头到尾没有碰过文件系统。它只知道「调用 window.files.pickAndRead(),等一个结果」。路径来自系统对话框,不是页面拼出来的字符串;大小限制、编码、异常处理都在主进程。这就是正确方向:能力放在主进程,页面只拿结果。
校验:参数、返回值、来源,一个都不能省
参数校验是 IPC 的第一道门。即使当前通道不收参数,也要把「以后加参数」当成必然:通道一旦对页面开放,页面就是不可信输入源。XSS 能执行页面脚本,也就能调用你暴露的每一个方法。所有参数都要检查类型、长度、范围、枚举值,不能直接塞进文件路径、命令行或 SQL。
ipcMain.handle('export:save', async (event, payload) => {
if (!payload || typeof payload.text !== 'string') {
return { ok: false, code: 'BAD_ARGS' };
}
if (payload.text.length > 5 * 1024 * 1024) {
return { ok: false, code: 'TOO_LARGE' };
}
if (typeof payload.name !== 'string' || payload.name.length > 100) {
return { ok: false, code: 'BAD_NAME' };
}
// 只在允许的目录里拼路径,再用相对路径确认没有越界
const baseDir = path.resolve(app.getPath('documents'));
const target = path.resolve(baseDir, payload.name);
const relative = path.relative(baseDir, target);
if (relative.startsWith('..') || path.isAbsolute(relative)) {
return { ok: false, code: 'BAD_PATH' };
}
await fs.writeFile(target, payload.text, 'utf8');
return { ok: true, path: target };
});
返回值和参数一样要约束。跨进程传的是结构化克隆后的数据,函数、类实例、DOM 对象、原型方法都过不去;传一个巨大的对象,序列化和反序列化会占掉两边的时间和内存。返回结果里不要夹带主进程的内部对象,也不要返回带敏感路径的错误原文。页面只需要知道「成功没有、失败属于哪一类」。
来源校验是第二道门。上面的 assertTrustedSender 做了两层:先确认 event.sender 是当前主窗口的 webContents,再确认发起调用的 frame URL 是本地页面。event.senderFrame 在极端情况下可能为空,所以要判空;URL 要按协议、主机、路径比对,不要只做 includes,否则一个精心构造的地址就能绕过。如果应用会加载远程页面、多个窗口或第三方 iframe,来源校验就不能省。
第三道门是错误处理。主进程的异常不会原样跨进程传过去:渲染进程收到的 reject 通常只有一句「Error invoking remote method 'xxx'」加上原始 message,堆栈指向的是渲染进程里的 invoke 调用,不是主进程出错的那一行。这意味着两件事:第一,真正的堆栈必须打在主进程日志里,最好带一个请求 id,方便和用户报错对上;第二,预期内的失败(取消、文件太大、格式不对)不要用 throw,而是返回结构化的 { ok: false, code },让页面能分支处理。
还有一层常被忽略:返回值也可能被页面伪造。如果页面判断「result.ok 为真就直接信任 result.path」,而页面本身已经被注入,攻击者可以绕过页面代码直接读到的只有你返回的数据,改不了主进程行为,但能误导用户界面。对安全敏感的操作,主进程不要依赖页面传来的「已确认」状态,自己再校验一次。
泄漏、卡死与沙箱:IPC 的三个常见坑
第一个坑是监听器泄漏。单页应用切路由时组件销毁,但 ipcRenderer.on 注册的回调还留在渲染进程的事件表里。每挂载一次加一个,切十次就有十个,事件一来全部执行,旧组件里的 DOM 引用、定时器、请求都跟着活着。更隐蔽的是,回调闭包捕获了大对象,内存看着一点点涨,用户只会说「用久了变卡」。
正确的做法是在预加载里把「订阅」包装成「订阅加退订」,并且不要把原始的 event 对象交给页面:
const { contextBridge, ipcRenderer } = require('electron');
contextBridge.exposeInMainWorld('progress', {
subscribe(handler) {
const listener = (_event, value) => handler(value);
ipcRenderer.on('download:progress', listener);
return () => ipcRenderer.removeListener('download:progress', listener);
}
});
页面在组件挂载时保存返回的退订函数,在卸载时调用。React 里对应 useEffect 的清理函数。如果是「只关心一次」的事件,用 once,别用 on 再手动判断。主进程侧同样有对称问题:ipcMain.handle 重复注册会抛异常,热更新或每开一个窗口注册一次就会踩到;把注册放在模块初始化时执行一次,或者用 removeHandler 明确清掉。
第二个坑是同步 IPC。ipcRenderer.sendSync 会阻塞整个渲染进程,直到主进程返回;主进程如果正忙,页面就完全卡住,动画、输入、关闭按钮全部无响应。有人用它读配置,觉得「就一次很快」,但主进程在启动时读磁盘、跑数据库迁移,恰好慢了几百毫秒,用户看到的就是程序假死。所有同步调用都应改成 invoke,把等待变成异步;主进程里的重活也不要同步跑,必要时丢给 worker 或 utility process。
第三个坑是沙箱。打开 sandbox: true 之后,预加载脚本只能用一小组受限 API,require('node:fs')、child_process、原生模块都不可用。这不是配置错了,而是设计如此:预加载运行在渲染进程一侧,必须假设页面可能被攻破。文件读写、进程启动、注册表操作都要放主进程,通过 IPC 暴露受控方法。如果你在预加载里看到「Cannot find module 'fs'」,正确反应是把这段逻辑搬到主进程,而不是去关沙箱。
还有一个容易被忽视的细节:contextBridge 暴露的对象不是原样共享,而是经过一次结构化克隆和函数代理。页面拿到的是副本,改它不会改到预加载里的对象;暴露函数时,参数也会被克隆。所以不要指望通过暴露一个可变对象来「双向同步状态」,状态应该用事件通知,或者每次调用重新取。
现象、原因与第一步
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
开沙箱后页面里 require('fs') 报错 | 预加载运行在沙箱里,Node 内置模块不可用 | 把文件操作搬到主进程,确认预加载只负责暴露方法 |
invoke 一直 pending,没有结果 | 通道名不一致、handle 没注册,或主进程处理函数抛异常后没被观察 | 核对通道名,检查主进程终端报错,确认注册发生在调用之前 |
| 切换页面后旧组件还在响应事件 | on 注册的回调没有移除,闭包一直持有旧状态 | 在组件卸载时调用退订函数,用 DevTools 看监听器数量是否随切换增长 |
| 第二次注册同一通道直接抛异常 | ipcMain.handle 不允许重复注册 | 把注册移到模块顶层只执行一次,必要时先 removeHandler |
| 渲染进程只收到一句「Error invoking remote method」 | 跨进程只传 message,主进程堆栈没有跟过来 | 在主进程按请求 id 打日志,把预期错误改成结构化返回 |
| 调用某个通道时窗口卡死几秒 | 用了 sendSync,或主进程在处理函数里同步做重活 | 改成 invoke,把耗时任务移出主线程或拆成异步步骤 |
页面里 window.files 是 undefined | 预加载路径错、沙箱下脚本报错,或 exposeInMainWorld 没执行到 | 看 DevTools 控制台的预加载错误,确认路径是绝对路径且文件存在 |
| 任意页面都能调用文件接口 | 只暴露了方法,没有校验调用来源 | 比较 event.sender 与主窗口,校验 senderFrame 的完整 URL |
边界与代价
第一,IPC 通道是长期合同。页面代码会迭代,主进程接口一旦被多个页面、插件或脚本依赖,改名和改参数就变成兼容性问题。通道名要有统一前缀和命名规范,参数结构尽量显式,版本变化时保留旧通道一段时间,或者一次改干净并同步所有调用方。随手起的 doSomething 这种名字,三个月后没人知道它到底做了什么。
第二,跨进程传输有成本。结构化克隆会复制数据,传一个几十 MB 的对象,渲染进程和主进程都要花时间序列化、反序列化,期间界面可能卡顿。大文件不要整个读进内存再传,传路径让主进程流式处理,或者用分块事件;图片、二进制数据可以考虑专门的协议或共享内存方案。IPC 适合传指令和小结果,不适合当数据总线。
第三,错误可观测性会下降。异常跨进程只剩一句话,堆栈丢失,时间线也难对齐。必须在主进程统一记录通道名、请求 id、耗时、结果码,渲染进程上报问题时带上同一个 id。没有这套东西,用户说「保存失败」,你只能让他在 DevTools 里复现,而生产环境根本开不了 DevTools。
第四,预加载脚本本身会变成一个小型 SDK。方法一多,参数格式、错误码、版本兼容都要维护;沙箱又限制了它能用的模块,不能随便引入大型依赖。合理的做法是把预加载控制在一份薄薄的适配层,复杂逻辑放主进程;如果确实需要组织代码,可以在构建时把预加载打包成单文件,而不是在运行时动态加载一堆模块。
第五,主进程是单线程的。一个处理函数里做同步文件读写、跑大量计算、等网络,会阻塞所有窗口的 IPC 和事件循环。耗时操作要异步化,CPU 密集型任务放到 worker 或 utility process,数据库连接要池化。渲染进程卡死用户还能关窗口,主进程卡死整个应用都没反应。
第六,安全边界不是「开了沙箱就结束」。沙箱限制了渲染进程的 Node 能力,但桥暴露的每个方法仍是攻击面;上下文隔离阻止页面篡改预加载对象,但页面被 XSS 后仍能调用暴露的方法。参数校验、来源校验、最小权限、内容安全策略、导航限制,要一起做才成立。下一篇会把这条边界完整展开。
小结与练习
IPC 的骨架是两条通道:要结果用 invoke 配 handle,要通知用 send 配 on。预加载脚本只做一件事:把主进程的能力包装成窄接口,通过 contextBridge 挂到页面上。参数、返回值、调用来源都要校验,预期错误返回结构化结果,意外错误留在主进程日志。监听器要有退订,同步调用要改异步,文件操作永远放主进程。
当天可以自己验证的练习:
- 运行示例,确认页面里
window.require是 undefined,而window.files.pickAndRead可以调用;再试着在预加载里require('node:fs'),观察沙箱下的报错。 - 把主进程处理函数里的
return { ok: false, code }改成throw new Error('读取失败'),对比渲染进程收到的错误信息,确认堆栈丢失。 - 给示例加一个「保存到文件」的通道,页面传文本内容,主进程校验类型、长度和目标目录,体会参数校验该怎么写。
- 写一个带
subscribe和退订的进度通道,在页面里反复进入、离开组件,打印监听器数量,确认没有增长。 - 把一次调用改成
sendSync,在主进程处理函数里加await new Promise(r => setTimeout(r, 3000)),观察窗口是否卡住,再改回invoke。
桥搭好之后,最后一个问题是这条边界到底该收多紧。下一篇讲桌面外壳的安全边界:沙箱、CSP 与 nodeIntegration。这一篇说明了「能力要放主进程」,下一篇要回答「哪些能力根本不该暴露、页面被注入时怎么把损失限制在最小」。