====== Electron ====== [[进程和线程]] [[主进程和渲染进程]] [[使用IPC进行通讯]] Electron 是一个用 HTML / CSS / JavaScript 编写跨平台桌面应用的**开源框架**,由 Chromium 渲染引擎与 Node.js 运行时组合而成,最初由 GitHub 团队发起,现由 OpenJS Foundation 托管维护。 一句话理解:**打包后的 Electron 应用,就是一个内置了 Chromium 与 Node 的可执行文件,它加载你的网页作为界面,同时把文件系统、菜单、托盘、通知等系统能力通过进程间通信交给界面使用。** 典型应用:VS Code、Slack、Discord、Figma 桌面版、Obsidian、Notion、1Password 8。 [[:electron:快速开始]] [[:electron:调试]] ===== 进程模型 ===== 这是理解 Electron 的第一道关,也是最容易出错的地方。 ^ 角色 ^ 运行环境 ^ 数量 ^ 职责 ^ | 主进程 main | Node.js 环境 | 全局唯一 | 创建与管理窗口、菜单、托盘,访问文件系统、调用系统 API、管理应用生命周期 | | 渲染进程 renderer | Chromium 多进程 | 每个窗口一个 | 只负责绘制界面,本质是网页;默认无法直接使用 Node | | 预加载脚本 preload | 渲染进程内、页面加载前执行 | 每个窗口一个 | 通过 ''contextBridge'' 把白名单 API 暴露给页面,充当中介 | 要点: * 主进程与渲染进程**不能直接互相调用函数**,必须通过 IPC 传递消息。 * 渲染进程里的 ''require''、''fs'' 等并非默认可用,需显式开放或经 preload 桥接。 * 打包后主进程代码与渲染进程代码路径不同,不能混用相对路径。 ===== 知识地图 ===== ==== 一、进程间通信(IPC) ==== * ''ipcMain.handle'' / ''ipcRenderer.invoke'':Promise 风格的请求-响应,推为首选 * ''ipcRenderer.send'' / ''ipcMain.on'':单向消息 * ''webContents.send'':主进程主动向指定窗口推送 * ''MessageChannel'' / ''MessagePort'':建立长期双向通道 * 多窗口之间的通信与主进程广播 * 传参限制:只能传结构化克隆可序列化的数据,函数、类实例、Proxy 会报错 ==== 二、安全模型 ==== Electron 的安全问题几乎都源于「给渲染进程开了太多权限」,务必掌握: * ''contextIsolation: true''(默认开启)、''nodeIntegration: false''(默认关闭)、''sandbox: true'' * 只通过 preload 暴露最小粒度的 API,**绝不整体暴露 ''ipcRenderer''、''require'' 或一个万能通信通道** * 主进程侧校验 IPC 参数与调用来源(''event.senderFrame'') * 设置 CSP(''Content-Security-Policy''),避免加载不可信的远程内容 * ''remote'' 模块已被废弃,不应用于新项目 * 调用 ''shell.openExternal'' 前校验 URL 协议 * 加载远程页面时要格外谨慎,等价于把系统权限交给外部站点 ==== 三、窗口管理 ==== * ''BrowserWindow'':尺寸与位置、''frame''、''titleBarStyle''、透明窗口、无边框窗口 * 父子窗口、模态窗口、多窗口与窗口状态持久化 * 多显示器与 DPI 缩放(''screen'' 模块) * ''WebContentsView''(新版推荐,用于在窗口内嵌入多个网页视图)与旧 ''BrowserView''、''webview'' 标签的取舍 * 显示时机:''show: false'' 配合 ''ready-to-show'' 避免白屏闪烁 ==== 四、应用生命周期 ==== * ''app.whenReady()'' 之后再创建窗口 * ''window-all-closed'':Windows / Linux 关窗即退出,macOS 通常保留 * macOS 的 ''activate'':点击 Dock 时若无窗口则重建 * ''before-quit'' / ''will-quit'':清理资源、取消未完成的写入 * ''app.requestSingleInstanceLock()'':单实例限制,配合 ''second-instance'' 聚焦已有窗口 * 启动性能:压缩 preload 工作量、窗口懒加载、延后非关键初始化 ==== 五、系统能力接入 ==== * 菜单 ''Menu''、上下文菜单、托盘 ''Tray'' * 通知 ''Notification''、任务栏进度与角标 * ''dialog'' 文件选择 / 保存、文件拖拽、''clipboard'' * ''globalShortcut'' 全局快捷键 * 自定义协议 ''protocol''(如 ''myapp'' 这类自定义 scheme)、开机自启、跟随系统主题 * 深链接与文件关联 ==== 六、原生与本地数据 ==== * 主进程直接使用 Node API:''fs''、''path''、''child_process''、''os'' * 原生模块:N-API / node-gyp 编译、''electron-rebuild''、ABI 版本对齐 * 本地存储方案:''electron-store''(JSON 配置)、better-sqlite3(关系型)、IndexedDB(前端侧) * ''safeStorage'' 加密敏感凭据,避免明文落盘 ==== 七、构建、打包与分发 ==== * 工程化:''electron-vite'' / Vite + TypeScript、''electron-forge''、''electron-builder'' * ''asar'' 归档、''extraResources''、资源路径(''app.getAppPath()''、''process.resourcesPath'') * 代码签名:Windows 需证书签名;macOS 需签名 + **公证 notarization**,否则用户无法打开 * 自动更新:''autoUpdater'' / ''electron-updater''、更新服务器、差量包、灰度发布 * 崩溃上报 ''crashReporter''、日志 ''electron-log'' * 多平台多架构产物:Windows x64 / arm64、macOS 双架构、Linux deb / AppImage ==== 八、调试与测试 ==== * 主进程调试:''--inspect'' 接入 Chrome DevTools * 渲染进程:内置 DevTools,可用 ''electron-devtools-installer'' 装框架插件 * 单元测试(Vitest / Jest)+ 端到端测试(Playwright;Spectron 已弃用) * 日志与崩溃定位:主进程与渲染进程日志分开收集 ==== 九、性能与体积 ==== * 内存占用偏高:每个窗口都对应一套 Chromium 渲染进程 * 安装包偏大:通常 80–150 MB 起,因为内嵌了 Chromium 与 Node * 优化方向:冷启动优化、减少常驻渲染进程、及时销毁不用的窗口 * 与 Tauri(Rust + 系统 WebView,包更小但渲染一致性依赖系统)、NW.js、CEF 的对比取舍 ==== 十、版本与升级策略 ==== * 约每 8 周发布一个大版本,**只维护最近 3 个** * 每个版本绑定固定的 Chromium / Node 版本,升级前先查兼容矩阵 * 大版本升级的常见破坏点:Node API 变更、默认安全选项收紧、原生模块需重编 ===== 高频踩坑 ===== * **白屏**:''loadFile'' 路径错误、CSP 拦截、preload 路径在打包后失效 * **An object could not be cloned**:IPC 传了不可序列化对象(函数、类实例、Proxy) * **打包后找不到资源**:''dirname'' 路径基准的语义在 asar 内会变化,应改用 ''app.getAppPath()'' 或 ''process.resourcesPath'' * **macOS 上关窗不退出**:这是符合平台习惯的行为,需在 ''window-all-closed'' 中区分平台 * **自动更新在开发模式不生效**:仅打包并签名的版本可用 * **原生模块 ABI 版本不匹配**:需针对 Electron 重编原生模块(''electron-rebuild'') * **生产环境误开 DevTools 或仍在加载 localhost**:加载地址应依据 ''app.isPackaged'' 分支 ===== 参考 ===== * 官方文档:[[https://www.electronjs.org/docs/latest/|electronjs.org/docs]] * 安全检查清单:[[https://www.electronjs.org/docs/latest/tutorial/security|Security Checklist]]