本文说明 Electron 的通信通道与预加载脚本。进程模型与生命周期见 Electron 架构与进程模型,通道的安全配置与校验要求见 Electron 安全加固,通信承载的本地能力见 本地能力集成,前端侧的请求与异步处理方式见 JavaScript 浏览器运行时 与 同步与异步,模块划分与构建见 模块化 与 前端工程化,页面级状态组织见 Vue2 工程实践。

一、起源

1.1 三类通信需求

需求 例子 通道形态
界面请求系统能力 打开文件、读取目录、保存设置 请求与响应
界面通知主进程 上报状态、触发退出、记录日志 单向通知
主进程通知界面 更新进度、外部参数唤起、系统事件 推送与订阅

1.2 通信是唯一的跨界通道

界面与系统能力被隔离在不同进程中,所有跨界行为都必须经过通道。这一约束带来两个后果:

  • 通道的暴露面就是应用的安全边界,暴露越宽风险越大。
  • 通道也是性能与稳定性的关键路径,数据如何序列化与传输直接决定开销。

1.3 取舍

选择 获得 付出
收窄通道(按能力暴露、参数校验) 安全边界清晰、易于审计 需要维护接口清单,新增能力要显式添加
暴露通用通道(把通信对象直接交给界面) 写起来方便 界面脚本可调用任意通道,隔离形同虚设

二、原理

2.1 预加载脚本的执行环境

维度 说明
执行时机 在渲染进程中、页面脚本执行之前运行
上下文 处在与页面脚本隔离的独立上下文中,两边的对象互不可见
可访问范围 在沙箱启用时只可使用受限的一组内置模块;文件与进程等能力需要通过主进程提供
生命周期 每个窗口一份,窗口销毁即释放;其中的状态不跨窗口共享

由此得到两条结论:

  • 预加载脚本适合做"能力封装与参数校验",不适合承载业务逻辑,因为业务逻辑会导致它随界面变化频繁改动。
  • 界面脚本不能通过修改全局对象影响预加载脚本,两边的全局对象是隔离的。

2.2 上下文桥接的暴露规则

桥接的作用是把预加载脚本中的函数暴露到页面脚本可访问的命名空间下。其规则限制了可暴露的内容:

能否暴露 类型 说明
可以 函数、原始值、可克隆的对象与数组 函数会被代理调用
不可以 类实例与原型方法、符号、不可克隆对象 原型链在传递中丢失,实例会退化为普通对象
不推荐 事件发射器、通信对象本身 会绕开受控接口,使任意通道可达

不能直接暴露通信对象本身是安全设计中最重要的一条:界面脚本一旦拿到它,就可以向任何通道发送消息,包括未在预加载中声明的能力,隔离的意义随之消失。正确做法是只暴露语义化的方法,通道名写在预加载脚本内部。

2.3 三类通道模式

模式 方向 实现方式 适用
请求与响应 界面到主进程再返回 调用接口返回承诺,主进程注册处理器 绝大多数系统能力调用
单向通知 界面到主进程 发送消息,主进程监听 日志上报、状态同步,不关心结果
推送与订阅 主进程到界面 主进程主动发送,界面注册监听 进度、外部唤醒、系统事件
流式通道 双向 建立端口,两端直接收发 持续数据传输与需要低延迟的交互

选择依据是"是否需要有结果返回"与"是否需要长期传输":一次性调用用请求与响应,持续数据用流式通道,事件广播用推送与订阅。

2.4 数据序列化

通道传输使用结构化克隆,因此存在明确的类型限制:

类别 行为
可传递 原始值、日期、正则、映射与集合、定型数组与二进制缓冲、普通对象与数组
不可传递 函数、符号、类实例的原型信息、宿主对象(界面节点等)、部分资源句柄
传递后变化 二进制缓冲在部分路径下会变为定型数组视图,需要显式转换

错误对象的传递需要特别注意:处理器中抛出的错误会在界面侧表现为拒绝,但自定义字段与方法通常不会保留,只剩消息文本。因此需要携带结构化错误信息时,应返回统一的结果对象(包含是否成功、错误码与消息),而不是依赖抛出异常。

// 推荐:统一结果结构,保留错误码与可读信息
// 主进程
ipcMain.handle('file:read', async (_event, payload) => {
    try {
        const content = await fs.readFile(payload.path, 'utf8');
        return { ok: true, data: content };
    } catch (err) {
        return { ok: false, code: err.code || 'READ_FAILED', message: err.message };
    }
});

2.5 命名与校验

要求 做法
通道命名 采用"领域加动作"的两段式命名,便于审计与避免冲突
参数白名单 处理器内逐项校验类型与范围,拒绝不符合的请求
发送方校验 确认消息来自预期的界面来源,避免被其他窗口或嵌入内容调用
能力最小化 一个通道只做一件事,避免提供带模式参数的通用接口
错误返回 统一为结果对象,不把底层异常原文直接暴露给界面

参数校验的必要性在于界面脚本可以构造任意参数,包括越界路径与超长字符串;把校验放在主进程才能形成有效约束,放在界面侧只是提示。

2.6 生命周期与泄漏

风险 成因 处置
订阅泄漏 界面反复注册监听而未清理 暴露的订阅方法应返回取消订阅函数
向已销毁窗口发送 窗口关闭后主进程仍在推送 发送前判断窗口是否已销毁
监听器数量告警 同一事件注册过多监听 合并监听或在注册前清理旧监听
重复注册处理器 模块被多次加载导致处理器重复绑定 处理器注册集中在应用启动时执行一次

2.7 性能取舍

场景 代价 做法
高频小消息 序列化与跨进程调度的固定开销累积 合并批量发送,或降低频率
大对象传输 序列化占内存与耗时 只传标识或文件路径,由接收方按需读取
持续数据流 每次调用都走请求响应开销大 使用流式通道直接对接
大量并发调用 主进程处理排队 做并发控制与去重,避免无意义重复请求

原则是"通道传引用、少传内容":把数据放在主进程可访问的位置,通道只传递定位信息,界面按需拉取。

2.8 与前端框架集成

推荐在界面侧把通道封装为服务层:服务层负责调用通道、把结果对象转换为可用的返回值或抛出业务错误、并在组件卸载时取消订阅。这样做有三个收益:

  • 组件不需要知道通道名与结果结构,界面与通道解耦。
  • 错误处理统一在一层完成,避免各调用处重复判断结果对象。
  • 订阅的注册与取消集中在服务层,降低泄漏风险。

三、实现

3.1 预加载脚本

// preload.js:只暴露语义化方法,通道名保留在本文件内
const { contextBridge, ipcRenderer } = require('electron');

// 订阅辅助:返回取消订阅函数,避免界面侧无法清理
function subscribe(channel, callback) {
    const listener = (_event, payload) => callback(payload);
    ipcRenderer.on(channel, listener);
    return () => ipcRenderer.removeListener(channel, listener);
}

contextBridge.exposeInMainWorld('desktop', {
    // 请求与响应:统一返回结果对象
    file: {
        open: (options) => ipcRenderer.invoke('file:open', options),
        read: (filePath) => ipcRenderer.invoke('file:read', { path: filePath }),
        save: (payload) => ipcRenderer.invoke('file:save', payload),
    },
    app: {
        getVersion: () => ipcRenderer.invoke('app:get-version'),
        // 单向通知:不需要结果
        reportError: (info) => ipcRenderer.send('app:report-error', info),
        quit: () => ipcRenderer.send('app:quit'),
    },
    task: {
        start: (payload) => ipcRenderer.invoke('task:start', payload),
        cancel: (id) => ipcRenderer.invoke('task:cancel', { id }),
        // 订阅:返回取消订阅函数
        onProgress: (callback) => subscribe('task:progress', callback),
    },
    window: {
        minimize: () => ipcRenderer.send('window:minimize'),
        toggleMaximize: () => ipcRenderer.send('window:toggle-maximize'),
    },
});

要点:不暴露通信对象本身;每个方法对应一个明确的通道;订阅方法必须返回取消订阅函数;通道名不进入界面代码。

3.2 主进程处理器

// ipc/index.js:集中注册处理器,并在启动时执行一次
const { ipcMain, dialog, BrowserWindow, app } = require('electron');
const fs = require('node:fs/promises');
const path = require('node:path');

// 允许的根目录白名单,防止越权访问
const ALLOWED_ROOTS = [app.getPath('documents'), app.getPath('userData')].map((p) => path.resolve(p));

function assertInsideAllowedRoot(target) {
    const resolved = path.resolve(target);
    const allowed = ALLOWED_ROOTS.some((root) => resolved === root || resolved.startsWith(root + path.sep));
    if (!allowed) {
        const err = new Error('路径不在允许范围内');
        err.code = 'E_PATH_NOT_ALLOWED';
        throw err;
    }
    return resolved;
}

function ok(data) { return { ok: true, data }; }
function fail(err) { return { ok: false, code: err.code || 'UNKNOWN', message: err.message }; }

function registerHandlers() {
    // 发送方校验:只接受来自预期界面的调用
    const assertTrustedSender = (event) => {
        const url = event.senderFrame?.url || '';
        if (!/^https?:\/\/localhost:5173|^file:\/\//.test(url)) {
            const err = new Error('来源不可信');
            err.code = 'E_UNTRUSTED_SENDER';
            throw err;
        }
    };

    ipcMain.handle('file:open', async (event, options = {}) => {
        assertTrustedSender(event);
        const win = BrowserWindow.fromWebContents(event.sender);
        const result = await dialog.showOpenDialog(win, {
            title: '选择文件',
            properties: ['openFile'],
            filters: Array.isArray(options.filters) ? options.filters : undefined,
        });
        if (result.canceled || !result.filePaths.length) return ok(null);
        return ok(assertInsideAllowedRoot(result.filePaths[0]));
    });

    ipcMain.handle('file:read', async (event, payload = {}) => {
        assertTrustedSender(event);
        try {
            // 参数校验:类型与必填项
            if (typeof payload.path !== 'string' || !payload.path) {
                const err = new Error('路径参数缺失');
                err.code = 'E_INVALID_ARGUMENT';
                throw err;
            }
            const target = assertInsideAllowedRoot(payload.path);
            const stat = await fs.stat(target);
            // 大小限制:避免一次读入超大文件
            if (stat.size > 5 * 1024 * 1024) {
                const err = new Error('文件过大,请使用分片读取');
                err.code = 'E_FILE_TOO_LARGE';
                throw err;
            }
            const content = await fs.readFile(target, 'utf8');
            return ok({ content, size: stat.size });
        } catch (err) {
            return fail(err);
        }
    });

    ipcMain.on('app:report-error', (event, info) => {
        // 单向通知:仅记录,不返回结果
        console.error('[renderer-error]', info?.message, info?.stack);
    });
}

module.exports = { registerHandlers };

3.3 推送与流式

// 主进程推送:发送前判断窗口是否已销毁
const { BrowserWindow } = require('electron');

function pushProgress(taskId, progress) {
    for (const win of BrowserWindow.getAllWindows()) {
        if (win.isDestroyed()) continue;
        win.webContents.send('task:progress', { taskId, progress });
    }
}

// 按需推送:只在窗口正在显示该任务时发送,减少无效消息
function pushTo(win, channel, payload) {
    if (!win || win.isDestroyed() || win.webContents.isDestroyed()) return;
    win.webContents.send(channel, payload);
}
// 流式通道:主进程侧建立端口并交给界面
const { MessageChannelMain } = require('electron');

function startStream(webContents) {
    const { port1, port2 } = new MessageChannelMain();

    port1.on('message', (event) => {
        // 收到界面的请求,回传数据块
        const { offset } = event.data;
        port1.postMessage({ offset, chunk: readChunk(offset) });
    });
    port1.start();

    // 把一端交给界面,另一端保留在主进程
    webContents.postMessage('stream:port', null, [port2]);
}

function readChunk() { return new Uint8Array(0); }
// 界面侧接收端口(在预加载脚本中完成,避免把端口对象暴露给页面脚本)
const { ipcRenderer } = require('electron');

ipcRenderer.on('stream:port', (event) => {
    const [port] = event.ports;
    port.onmessage = (e) => {
        // 通过回调把数据交给页面
        onStreamData(e.data);
    };
    port.start();
});

要点:流式通道适合持续数据传输,但端口对象同样不应直接暴露给页面脚本,应由预加载脚本包装为受控接口。

3.4 界面侧服务封装

// services/desktop.js:把通道封装为服务层,统一处理结果与错误
const api = window.desktop;

function unwrap(result) {
    if (!result?.ok) {
        const err = new Error(result?.message || '操作失败');
        err.code = result?.code || 'UNKNOWN';
        throw err;
    }
    return result.data;
}

export const desktopService = {
    async openAndRead(options) {
        const filePath = unwrap(await api.file.open(options));
        if (!filePath) return null;                 // 用户取消
        return unwrap(await api.file.read(filePath));
    },
    async save(payload) {
        return unwrap(await api.file.save(payload));
    },
    startTask(payload) {
        return api.task.start(payload);
    },
    // 订阅:返回取消订阅函数,交由组件在卸载时调用
    onTaskProgress(callback) {
        return api.task.onProgress(callback);
    },
};
// 组件中使用:在挂载时订阅,在卸载时取消
export default {
    data() {
        return { progress: 0 };
    },
    mounted() {
        this.unsubscribe = desktopService.onTaskProgress((payload) => {
            this.progress = payload.progress;
        });
    },
    beforeDestroy() {
        // 必须取消订阅,否则窗口关闭后仍会收到消息
        this.unsubscribe?.();
    },
};

3.5 常见问题对照

现象 常见原因 处置
调用通道报方法不存在 预加载脚本未加载或方法名不一致 核对预加载路径配置与暴露的方法名
页面脚本拿不到暴露的对象 暴露在窗口就绪之前或命名冲突 确认暴露时机与命名空间名称
传递的对象丢失了方法 结构化克隆不保留原型 只传数据,把方法留在各自进程内
抛出异常后界面只看到一句话 自定义错误字段未被保留 改为返回统一结果对象
处理器报错但界面未感知 使用了单向通知而非请求与响应 需要结果时改用请求与响应模式
窗口关闭后界面仍收到消息 订阅未取消或未判断窗口是否已销毁 取消订阅并在发送前判断窗口状态
控制台出现监听器数量告警 重复注册监听未清理 取消旧监听或合并为单个监听
处理器被重复执行 模块被多次加载导致重复注册 处理器注册集中在启动时执行一次
高频更新时界面卡顿 每次微小变化都通过通道发送 合并批量推送或降低推送频率
传输大文件时内存升高 大对象整体序列化传输 只传路径或使用流式通道分片传输
越权访问了其他目录 仅在前端做了路径校验 在主进程做路径白名单校验
二进制的类型与预期不符 跨进程传递后变为定型数组视图 接收侧显式转换为需要的类型

四、总结

  1. 隔离之后所有跨界行为都经过通道,通道的暴露面就是应用的安全边界,也是性能与稳定性的关键路径。
  2. 预加载脚本在每个窗口内、页面脚本之前执行,处于独立上下文,沙箱启用时只能使用受限的内置模块。
  3. 上下文桥接只能暴露函数与可克隆数据,类实例的原型信息会在传递中丢失。
  4. 绝不能把通信对象本身暴露给页面脚本,否则任意通道可达,隔离形同虚设;应只暴露语义化方法并让通道名留在预加载脚本内。
  5. 三类通道模式按"是否需要结果"与"是否持续传输"选择,持续数据使用流式通道。
  6. 通道使用结构化克隆,错误对象的自定义字段不会保留,需要携带结构化错误时应返回统一结果对象。
  7. 通道命名采用"领域加动作",参数在主进程侧做白名单校验,并校验消息来源,能力按最小粒度暴露。
  8. 订阅方法必须返回取消订阅函数,推送前必须判断窗口是否已销毁,处理器注册应集中在启动时执行一次。
  9. 通道应传引用而非内容:大对象只传路径或标识,高频消息合并批量发送,持续数据使用流式通道。
  10. 界面侧应把通道封装为服务层,统一处理结果结构与错误,并把订阅与取消订阅集中管理。