★ FEATURED ARTICLE Electron 这个框架几乎是现在聊跨平台桌面应用开发时绕不开的名字。很多人看到“写一套代码同时跑在 Windows、macOS、Linux”的第一反应是“真有这种好事”我最初接到一个内部工具需求时也这么想过。当时团队需要一个能扫描本地文件、做批量处理的桌面小工具Web 页面受限于浏览器权限原生开发又不想维护三套代码最后选了 Electron。说实话上手的难度比我想象中低坑也比想象中多。这篇文章把我整个踩坑过程整理成一份可以照着做的参考适合用 HTML/CSS/JS 写过网页、但对桌面端还不熟的前端同学也适合正在做技术选型的开发者。读完你至少能搞清楚Electron 为什么能跨平台、项目怎么初始化、进程间通信怎么做、打包和自动更新怎么配以及常见白屏和崩溃怎么排查。1. 为什么选Electron来做跨平台桌面应用1.1 传统跨平台桌面开发到底难在哪在拿到那个内部工具需求时我先盘了一遍可选方案。原生开发听起来很美Windows 上基于 Win32 或 .NETmacOS 上基于 AppKitLinux 上再见 GTK 或 Qt。但问题是一套业务逻辑要写三遍每个平台还有各自的生命周期、窗口管理、权限模型。团队里没有专做客户端的人让前端去补三套原生栈短期根本不现实。Qt 和 Flutter 这类框架也考虑过。Qt 的 C 和 QML 学习曲线不低Flutter 的桌面端虽然起来了但对系统 API 的调用还是绕一层。更重要的是项目里已经有大量现成的 Web 端页面和组件如果能直接复用开发速度会快一大截。Electron 恰好踩在这个点上它把浏览器和本地能力打通了前端同学几乎零门槛就能写出桌面应用。当然代价也明摆着安装包大、内存占用高、启动比原生慢。后面我会细说这些坑。技术选型本质上是取舍不是找一个天下无敌的框架而是找一个团队能长期维护、业务能低成本迭代的组合。1.2 Electron的原理浏览器加Node.js的组合很多第一次接触 Electron 的人容易被“原理”两个字吓住。拆开看其实很朴素Electron 应用里内置了一个 Chromium 内核又内置了一个 Node.js 运行时。你用 HTML/CSS 写界面Chromium 负责把页面渲染出来你用 JavaScript 写业务逻辑Node.js 负责访问文件系统、执行子进程、调用系统 API。这个组合跑起来以后按照职责分成两类进程。主进程是应用的门面负责创建窗口、管理应用生命周期、处理系统菜单和托盘渲染进程是窗口里的页面一个 BrowserWindow 对应一个渲染进程。如果开了五个窗口就有至少五个渲染进程在跑。更重要的是这两类进程不能直接互相访问。我的理解里可以想象成一家餐厅主进程是前厅经理每次开新窗口就是安排一张新餐桌渲染进程是后厨师傅各自管好自己锅里的菜IPC 就是传菜口前厅要后厨出菜必须走这个口子下单。一旦桌子上直接伸手进后厨秩序就乱了。所以 Electron 才要反复强调主进程、渲染进程、preload 脚本三者之间的边界。1.3 不是所有桌面应用都适合Electron选 Electron 之前先对照一下自己的场景。它会放大前端团队的优势也会放大“包大、耗内存”的劣势。适合的场景不适合的场景内部管理系统、后台管理客户端对性能要求极高的 3A 游戏、渲染引擎数据可视化大屏、图表工具安装包要求严格控制在几十 MB 内的工具桌面效率软件、文档处理常驻低配机器且需要极致省内存的托盘工具硬件设备配套的电脑端程序核心逻辑依赖高频计算、需要直啃 CPU 的科学软件音视频客户端的外壳层已有成熟原生团队、需要深度接入系统私有能力的产品比如我们当时要做的本地文件扫描工具核心操作是读目录、看后缀、批量改名Electron 完全扛得住真正耗时的数据处理可以用子进程去做界面无卡顿。反过来如果我要写一个硬核图像处理软件每个像素都要用 WebAssembly 去抠那我会先做性能测试再决定而不是闭眼入。2. 从零搭一个Electron应用先让窗口跑起来2.1 环境准备Electron 开发本质上是 Node.js 项目所以第一步就是准备好 Node.js。我建议直接装 LTS 版本不要追最新大版本因为一些原生模块和构建工具可能还没来得及跟上。装完以后在终端里跑node -v npm -v能看到版本号说明环境基本可用。编辑器随意现代前端编辑器都行终端建议用系统自带或者 Git BashWindows 下尽量避免把命令写在 PowerShell 里踩不必要的转义坑。首次安装 Electron 时会下载一个不小的二进制包如果网络慢可以把 npm 镜像源切换成国内常用镜像或者让下载走离线安装包之后再正常开发。这里不用太纠结装好能用就行。2.2 最简项目结构先不急着上脚手架我建议新手手动搭一个最小工程彻底理解每个文件的作用。新建一个目录然后mkdir my-desktop-app cd my-desktop-app npm init -y npm install --save-dev electronlatest然后创建三个核心文件main.js、preload.js、index.html。目录结构长这样my-desktop-app/ ├─ main.js ├─ preload.js ├─ index.html └─ package.jsonmain.js 内容如下const { app, BrowserWindow } require(electron); const path require(path); function createWindow() { const win new BrowserWindow({ width: 1024, height: 768, webPreferences: { preload: path.join(__dirname, preload.js), contextIsolation: true, nodeIntegration: false } }); win.loadFile(index.html); } app.whenReady().then(() { createWindow(); app.on(activate, () { // macOS 上点击 Dock 图标且没有其他窗口时重新创建窗口 if (BrowserWindow.getAllWindows().length 0) createWindow(); }); }); app.on(window-all-closed, () { // macOS 上关掉所有窗口后应用通常不退出 if (process.platform ! darwin) app.quit(); });preload.js 里先写一个最小桥接层const { contextBridge } require(electron); contextBridge.exposeInMainWorld(desktop, { platform: process.platform });index.html 里随便放一行欢迎文字。最后在 package.json 中确认 main 字段指向 main.js然后在 scripts 里加一句scripts: { start: electron . }执行npm start如果能弹出一个窗口恭喜你已经完成了第一个 Electron 应用。这一步跑通后再往里加功能会顺畅很多。2.3 主进程和渲染进程职责先分清很多新手踩的第一个坑就是把所有代码都往 main.js 里堆。窗口创建、业务逻辑、页面跳转混在一起代码写不了多少就开始失控。我的建议是主进程只管应用级的事包括窗口、菜单、系统托盘、文件对话框、自动更新渲染进程只管页面展示和用户交互需要访问系统能力时通过 preload 暴露的 API 发起请求由主进程去执行。为什么不能直接在渲染进程里写 Node.js 代码因为渲染进程本质上是浏览器页面。Electron 20 以后默认开启了沙箱渲染进程处于隔离环境直接写require(fs)会失败这是保护机制不是 bug。如果你看到教程里在渲染进程直接const { ipcRenderer } require(electron)多半是很老的写法别照着抄。一定要记住主进程有完整的 Node.js 权限但千万别把它当服务器用渲染进程没有本地权限但千万别让它通过new Function之类的手段绕过隔离。安全边界从项目第一天就得立起来。3. 跨窗口通信进程间通信与数据安全3.1 IPC通信看起来神秘其实就两步Electron 里最常见的需求是用户点一个按钮然后读取本地文件并回显到页面上。这个流程就是典型的进程间通信。现在推荐用ipcMain.handle和ipcRenderer.invoke的组合它返回 Promise写法贴近前端习惯错误处理也更简单。在 preload.js 中暴露一个方法const { contextBridge, ipcRenderer } require(electron); contextBridge.exposeInMainWorld(desktop, { pickFile: () ipcRenderer.invoke(pick-file) });在主进程中响应const { ipcMain, dialog } require(electron); const fs require(fs); ipcMain.handle(pick-file, async (event) { const { canceled, filePaths } await dialog.showOpenDialog({ properties: [openFile], filters: [{ name: 文本文件, extensions: [txt, md, log] }] }); if (canceled || filePaths.length 0) return null; return fs.promises.readFile(filePaths[0], utf-8); });在渲染进程里点击按钮document.querySelector(#pick-btn).addEventListener(click, async () { const content await window.desktop.pickFile(); document.querySelector(#content).textContent content || 没有选择文件; });这套链路清晰渲染进程只能调用window.desktop上暴露的固定方法不能直接拿到ipcRenderer对象去监听任意频道。如果某些业务需要主进程主动推送消息比如任务进度通知也可以用webContents.send加ipcRenderer.on但通知类消息应尽量避免把敏感数据透传。3.2 安全配置必须从第一天就做对我见过不少项目一上来就直接把nodeIntegration设为 true图省事。这相当于把一把菜刀递给一个还没学会用的小朋友风险极大。现在写 Electron 应用的默认配置应该这样contextIsolation: true渲染进程和 preload 环境隔离页面里拿不到 Node.js API。nodeIntegration: false让渲染进程保持浏览器环境不要开放 Node.js 执行权限。sandbox: true开启渲染进程沙箱限制系统调用。加载远程网页时不要同时打开 Node.js 权限。外部链接尽量用shell.openExternal并先校验协议只允许 http、https、mailto 等安全协议。这些配置不是装饰品。Electron 应用一旦被注入恶意脚本攻击面就是整个用户系统不是页面级的小问题。所以哪怕只是做个内部工具也别省这一步。3.3 本地数据持久化怎么选桌面应用没有后端数据存哪里就靠你自己定。我的经验是分场景选配置项、用户偏好用 electron-store 这类 JSON 存储库本质是往用户数据目录里写一个 JSON 文件简单可靠。简单键值数据也可以直接用 localStorage但注意 localStorage 在 Electron 里跟用户数据目录绑定清缓存策略不同适合临时数据。结构化业务数据用 SQLite。管理工具、记账应用、本地知识库这类需求用 better-sqlite3 这类库很顺手。日志类数据直接写文件流别塞进数据库方便按天滚动清理。还要记住一个原则不要往安装目录写文件。程序装在系统盘时用户目录可能没有写权限而且应用更新后安装目录会被替换数据会丢。正确做法是用app.getPath(userData)拿到一个固定但可写的用户数据目录然后把数据都放这里。4. 打包、分发与自动更新最容易被低估的环节4.1 打包工具怎么选开发时窗口能跑起来只能算完成一半。真正把应用交给别人用还得过打包这一关。常见的方案有三个工具特点适合场景electron-builder配置丰富支持多平台产物、安装包、自动更新大多数项目首选Electron Forge官方脚手架模块化集成性不错喜欢官方生态、插件化开发的人electron-packager只生成解压目录不做安装包临时分发、内部测试我一般默认选 electron-builder。它对 Windows 的 NSIS 安装包、macOS 的 dmg、Linux 的 AppImage 都有现成支持而且内置自动更新模块 electron-updater能省不少事。要注意的是跨平台打包最好在目标平台上打不要在 Windows 上硬打 mac 包很多原生依赖和签名流程会出问题。4.2 一份能用的electron-builder配置在 package.json 里加一个 build 字段像这样{ appId: com.example.myapp, productName: 模拟项目X, directories: { output: dist }, files: [ main.js, preload.js, renderer/**/* ], asar: true, win: { target: nsis }, mac: { target: dmg, category: public.app-category.developer-tools }, linux: { target: AppImage } }然后执行npx electron-builder它会在 dist 目录下生成对应平台的安装包。这几个字段有讲究appId建议用反域名格式别随手写一个files决定哪些文件被打进应用包能用 glob 排除掉测试文件和源码地图能显著减小体积asar开启后所有源码会被打包进一个归档文件能防止用户轻易看到源码结构。图标也别忘了准备Windows 需要 .icomacOS 需要 .icnsLinux 常用 PNG 图标。没有图标的时候 electron-builder 能打出包但安装后图标非常敷衍观感很差至少要准备一套 512x512 以上的主视觉。4.3 自动更新落地时要注意的事我之前踩过最深的坑是代码里加了自动更新但更新服务器地址没配好结果某个测试机一直停留在旧版本。Electron 的更新逻辑本身不复杂主进程里引入 electron-updater然后const { autoUpdater } require(electron-updater); autoUpdater.logger null; // 不开日志的话出问题时很难定位 autoUpdater.checkForUpdatesAndNotify();更重要的是把publish字段配好publish: [ { provider: generic, url: https://example.com/updates/ } ]这个 URL 只要是一个静态文件服务就行目录下放打包生成的安装包和latest.yml客户端启动时去检查版本号。Windows 上使用 NSIS 安装包时更新流程支持得比较好macOS 上必须做代码签名和公证否则系统会拦截更新后的应用。很多团队自己内部用没做签名也能跑但一旦要对外分发这步绕不开。4.4 安装包体积优化Electron 应用动不动上百 MB确实让不少人劝退。优化思路不是追求把 Chromium 干掉而是尽量别往包里装不必要的东西。第一确认files列表只包含构建产物、入口文件和必要资源源码里别带node_modules中开发依赖。第二前端构建时关闭 source map压缩代码和样式别把几千张原始图片放进包里。第三如果只是读取的静态资源可以用 asar 归档如果是外部可执行文件或动态更新的内容放到extraResources而不是files避免每次更新都跟安装包捆绑。第四开启compression的 maximum 选项安装包能再瘦一圈代价是打包时间变长。开发机性能允许的话还是值得的。体积优化说到底是个平衡题。对内部工具来说我宁可选清晰的项目结构而不是极限压包对外分发时再把体积指标提上优先级。5. 实操中常踩的坑能救一个是一个5.1 窗口白屏八成是加载路径问题白屏是 Escape 开发里出现频率最高的问题原因也高度集中在路径上。开发环境用loadFile(index.html)没问题一旦打包后主进程的工作目录变了相对路径就找不到了。更稳的写法是win.loadFile(path.join(__dirname, dist/index.html));如果加载的是本地文件一定要用path.join拼接绝对路径不要用字符串拼接。如果你用了 Vite 或 Webpack 这类构建工具渲染进程的入口是构建后的 HTML 文件主进程加载的就是dist里的文件而不是源码里的 index.html。白屏排查还有一个固定套路先在createWindow里临时加一行win.webContents.openDevTools()让开发者工具自动弹出来然后看 Console 报什么错。报错信息里通常会写清楚是文件不存在、CSP 阻止了资源加载还是 preload 脚本解析失败。定位到具体原因比盲改配置高效得多。5.2 渲染进程崩溃别让它拖垮整个应用Electron 的渲染进程是隔离的单个页面崩溃一般不会直接把主进程带崩但用户看到白屏或卡死也会很困惑。建议在主进程里监听渲染进程异常退出win.webContents.on(render-process-gone, (event, details) { // details.reason 可能是 crashed、oom 等 dialog.showMessageBox({ type: warning, message: 页面异常退出即将重新加载, }); win.reload(); });注意不要无限重载否则崩溃原因没解决应用会反复弹窗。正确的做法是先记录日志再根据异常原因决定是否重载。内存溢出导致的崩溃重载也不一定有用这时候要考虑是不是某个瞬间加载了超大文件或者窗口数量太多挤爆了内存。我之前处理过一次 OOM 崩溃最后发现是一个日志文件无限增长渲染进程里一直用正则做高亮每敲一个字符就扫一遍全部文本CPU 和内存同时上去了。5.3 打包后找不到文件别用__dirname想当然开发时__dirname指向当前文件所在目录打包后应用代码被放进 app.asar 归档里路径逻辑就变了。如果你要动态读取一个外部资源比如一个自定义字体、一个命令行工具、一张用户导入的图片就不能理所当然地放在源码目录下读取。正确姿势是把这类文件放到extraResources里extraResources: [ { from: resources/tools/, to: tools/ } ]然后通过process.resourcesPath拼路径访问const toolPath path.join(process.resourcesPath, tools/my-tool.exe);这一点特别容易被忽略。我见过某个项目在开发环境一切正常一打包就报“文件不存在”最后定位到就是因为它把数据文件放在项目根目录打包后项目根目录变成了归档内部浮于表面的路径根本不可用。5.4 调试主进程的三种方法渲染进程的调试可以开开发者工具主进程调试要麻烦一点。我最常用的几种方式在入口启动命令里加上--inspect9222然后用浏览器调试器去连接适合查看主进程堆栈。用任意现代编辑器配置 launch 调试环境给 main.js 打断点方式跟调试 Node.js 差不多。主进程里加 electron-log 这类日志库从启动开始落盘记录线上问题靠日志排查。主进程不像渲染进程有可视化界面报错经常只在终端一闪而过。所以我从一开始就养成习惯所有关键操作都打日志包括创建的窗口、调度的任务、更新检查结果。这个习惯在排查问题时能省下一整晚时间。6. 用了一个月Electron之后的个人心得如果你只是听别人说“Electron 就是套皮浏览器”可能会下意识拒绝它。但真实做下来我对它的评价是一个能快速把团队前端能力转化成桌面产品的工具上限不低下限也明确。它适合的地方比如内部工具、企业级管理软件、垂直业务客户端确实能带来很高的交付效率它不适合的地方比如高频计算、超小体积、极致性能也有明确边界。我个人实际使用中的体会是不要一上来就搭一套特别复杂的脚手架。先做一个能打开窗口、能读写本地文件、能打包安装的最小闭环再逐步加 IPC、加自动更新、加安全配置。这样每一层逻辑都清楚出了问题也知道该去哪一层排查。等到项目跑顺了再根据业务需求决定要不要引入前端框架、要不要拆进程、要不要做增量更新。最后再分享一个让我从“打包后白屏三小时”里爬出来的经验用app.isPackaged区分开发环境和生产环境主进程里写两套入口逻辑const isDev !app.isPackaged; if (isDev) { win.loadURL(http://localhost:5173); } else { win.loadFile(path.join(__dirname, dist/index.html)); }这一行判断能在你每次切换环境时少走一大段弯路。Electron 不难难的是一开始就把该有的边界、配置、审计意识立起来。把这些基本功打牢后面所有功能都是在安全的地基上叠加。
阅读完成 · 觉得有帮助？
