Electron
Electron 是一个用 HTML / CSS / JavaScript 编写跨平台桌面应用的开源框架,由 Chromium 渲染引擎与 Node.js 运行时组合而成,最初由 GitHub 团队发起,现由 OpenJS Foundation 托管维护。
一句话理解:打包后的 Electron 应用,就是一个内置了 Chromium 与 Node 的可执行文件,它加载你的网页作为界面,同时把文件系统、菜单、托盘、通知等系统能力通过进程间通信交给界面使用。
典型应用:VS Code、Slack、Discord、Figma 桌面版、Obsidian、Notion、1Password 8。
进程模型
这是理解 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文件选择 / 保存、文件拖拽、clipboardglobalShortcut全局快捷键- 自定义协议
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分支
参考
- 官方文档:electronjs.org/docs
- 安全检查清单:Security Checklist