写Electron这块的内容其实我早就想动手了。前后折腾了好几个项目——从给内部做的桌面运维小工具到把一套Vue管理后台完整封装成客户端再到后面帮同事排查那种“打包完就白屏”的玄学问题。Electron这个东西说简单是真简单一个浏览器壳子套上Node能力HTML页面摇身一变就成了桌面应用但说复杂也真复杂主进程、渲染进程、预加载脚本、IPC通信、菜单、打包配置任何一个环节没理清楚项目一大了就开始到处漏风。这篇速查手册就是基于我实际踩坑经验整理出来的把最常碰到的配置、模板、坑点都放在一起。这篇内容适合两类人看一是刚接触Electron、想搞清楚主进程和渲染进程到底怎么回事的新手二是已经上手但每次写IPC、调菜单、打包都要翻文档老半天的“熟练工”。看完你至少能直接拿走一套能跑的模板然后照着改。1. 为什么桌面应用开发绕不开Electron1.1 Electron到底解决了什么问题先说个直观的对比。过去要做桌面软件Windows上多半是C#配WinForms或WPFmacOS上是Swift配AppKitLinux更是各发行版各玩各的。你花大力气写完一套界面换个系统基本等于重写。更别提界面这件事本身就不是后端开发者的强项——写个表单、调个布局、处理个焦点事件能磨掉你半天心态。Electron的核心思路就是“用Web技术栈做桌面应用”。它把Chromium浏览器的渲染引擎和Node.js服务端运行环境打包在一起让你能用HTML、CSS、JavaScript去构建桌面客户端。同一套代码Windows能跑、macOS能跑、Linux也能跑顶多打包和适配的时候各自调一调。这个价值在团队里如果正好有前端工程师的情况下尤其明显前端同学不用从头学C或者C#后端同学也不用硬啃GUI框架的文档。我自己的体会是Electron最适合那类“管理系统”“数据看板”“内部工具”的项目。这类需求的特点是要展示大量表格、图表、表单交互逻辑集中在页面上同时又希望它有独立窗口、能访问本地文件系统而不是纯粹开个浏览器输地址。Electron恰好把这些都覆盖了窗口归Electron管页面交互归Web技术管本地能力归Node管。1.2 什么情况下要慎重选它当然Electron也不是万能钥匙。最典型的负面印象是“包体积大”——一个最简单的应用装上Electron打包出来少说一百多兆。这是因为里面塞了一个完整的Chromium。另外就是内存占用每个窗口对应一个渲染进程开三四个窗口内存分分钟上去。你要是做一个常驻后台、对资源极其敏感的小工具Electron不一定是最优解Tauri这类用系统WebView的方案会更轻。还有一个容易被忽视的点如果你的核心逻辑是重CPU计算、图像处理、音视频编解码这类活儿Electron的JS生态做起来会比较吃力。不是说做不了而是性能和那种底层语言写出来的差距比较明显。这种情况我更建议把重活儿拆成独立的原生模块或者子进程让Electron只负责界面调度。我的建议是项目规模中等、团队以Web技术为主、跨平台是硬需求、交付周期又紧——选Electron没毛病。反过来说如果你有极端的包体积要求、内存敏感、或者核心逻辑完全绕不开底层API——建议三思。2. 开篇第一课主进程和渲染进程到底怎么分工2.1 主进程到底是干什么的Electron应用启动后第一个被创建的是主进程。它运行在Node.js环境中拥有完整的Node能力——读写文件、访问网络、使用操作系统API都可以直接做。主进程的生命周期是整个应用的生命周期应用启动它启动应用退出它退出。它也是整个应用的“调度中心”所有原生窗口的创建、关闭、最小化包括后续讲到的应用菜单、系统托盘、对话框都是由主进程来管的。一个最直观的例子是创建窗口。你在主进程里调用new BrowserWindow()Electron才去创建一个新的窗口。窗口里的内容是什么加载一个远程URL或者加载本地打包好的HTML文件都由主进程决定。2.2 渲染进程又是怎么回事每个BrowserWindow实例都会开启一个独立的渲染进程。这个进程可以理解成“一个跑在Chromium里的网页”的环境你熟悉的DOM操作、CSS布局、浏览器API在这里都是可用的。渲染进程里你可以正常写Vue、写React和平时做网页开发几乎没区别。整个架构可以简单理解成主进程是老板负责申请资源、创建窗口、对接系统能力渲染进程是员工负责把页面内容画出来、和用户交互。老板和员工是隔离的——渲染进程不能直接碰Node的API主进程也不直接碰用户的点击事件。这个隔离是刻意的安全设计Electron的文档里反复强调“渲染进程不可信”因为渲染进程加载的内容如果来自网络理论上可能被注入恶意脚本。2.3 新手最容易犯的错在渲染进程里直接写Node代码这块我必须多写几句因为我见过太多人在这个点上栽跟头。有人直接在Vue组件里写上const fs require(fs) fs.readFileSync(/path/to/file)然后跑起来发现require is not defined或者直接白屏。原因很简单默认情况下渲染进程的nodeIntegration是关闭的。这是Electron从安全角度考虑的默认选项——一旦打开页面上任何被执行的脚本都能拿到Node的全部能力这等于把整个系统权限暴露给了页面。所以你在渲染进程里不能直接用require因为你压根在浏览器环境的沙箱里。正确的做法是把需要Node能力的事情交给主进程用IPC机制来回传数据。这个我会在下一节展开。关于这部分的架构关系我用一张表帮你快速理解维度主进程渲染进程运行环境Node.jsChromium浏览器环境核心能力窗口管理、系统API、文件、网络DOM、CSS、页面渲染能否用DOM不能能能否直接读写文件能默认不能数量一个每个窗口一个关闭影响应用退出仅关闭当前窗口3. IPC通信Electron开发的核心必修课3.1 从ipcMain和ipcRenderer这两个“信使”说起IPC全称是Inter-Process Communication也就是进程间通信。在Electron里主进程和渲染进程之间的所有消息传递都要走IPC。Electron为这个机制提供了一对核心模块ipcMain和ipcRenderer。ipcMain注册在主进程里负责接收来自渲染进程的消息并处理ipcRenderer注册在渲染进程里负责发消息和接收主进程的回复。最基础的用法是“渲染进程发主进程收”。渲染进程里这样写// 渲染进程 const { ipcRenderer } require(electron) ipcRenderer.send(window-minimize)主进程里这样写// 主进程 const { ipcMain, BrowserWindow } require(electron) ipcMain.on(window-minimize, (event) { const win BrowserWindow.fromWebContents(event.sender) win.minimize() })这里面有两点值得注意。第一event.sender是一个webContents对象它指代“发消息的那个窗口”主进程可以通过它拿到对应的BrowserWindow实例第二消息通道名称这里是window-minimize两端必须完全一致否则消息就石沉大海。3.2 遇到ipcRenderer is not defined怎么办这里有一个很现实的问题现在的项目基本都是脚手架生成的前端工程渲染进程用Vue或者React构建。如果你直接在前端代码里写require(electron)大概率会碰到ipcRenderer is not defined。原因在于渲染进程默认是禁用了Node集成的同时前端的构建工具Webpack、Vite环境里也没有Electron的模块机制。在这个前提下你直接引入electron模块编译阶段可能不报错但运行时拿不到ipcRenderer对象。最稳妥、也是Electron官方推荐的解法是为渲染进程配置一个“预加载脚本”在脚本里用contextBridge暴露一个安全的接口给渲染进程。具体这么做// preload.js const { contextBridge, ipcRenderer } require(electron) contextBridge.exposeInMainWorld(electronAPI, { minimize: () ipcRenderer.send(window-minimize), onUpdate: (callback) { ipcRenderer.on(update-message, (_event, data) callback(data)) } })然后在主进程创建窗口时指定预加载脚本const win new BrowserWindow({ width: 1200, height: 800, webPreferences: { preload: path.join(__dirname, preload.js), contextIsolation: true, nodeIntegration: false } })这样在渲染进程的Vue组件里你就能直接调用window.electronAPI.minimize()而完全不需要关心底层的IPC细节。这个模式的好处是渲染进程始终只接触你暴露出的一小撮方法拿不到完整的Electron能力安全性和可维护性都更高。3.3 单向通信、双向通信、广播三种场景分别怎么写实际开发中你很快会发现光靠send和on还不能覆盖所有场景。有些时候你需要“问一句、答一句”双向通信有些时候主进程要主动给所有窗口推消息广播。下面我把三种模式都列出来方便你照着抄。单向通信渲染进程发给主进程主进程不回复// 渲染进程 ipcRenderer.send(log-message, user clicked button) // 主进程 ipcMain.on(log-message, (_event, message) { console.log(message) })双向通信渲染进程发消息主进程处理完再回复渲染进程侧用invoke发送并接收一个Promiseconst result await window.electronAPI.getFileContent(/path/to/file)主进程侧用ipcMain.handle来处理ipcMain.handle(get-file-content, async (_event, filePath) { const content await fs.promises.readFile(filePath, utf-8) return content })invoke/handle这对组合是我在项目里用得最多的原因很直接它天然支持异步而且在渲染进程侧写法最接近普通的函数调用——不用注册监听器不用管理事件销毁拿到返回结果就是await一下的事。主进程广播向所有打开的窗口推送消息BrowserWindow.getAllWindows().forEach(win { win.webContents.send(data-refreshed, newData) })渲染进程侧照常监听window.electronAPI.onDataRefreshed((data) { // 更新页面数据 })广播场景最典型的就是“主进程在后台检测到文件变化/网络状态变化/数据更新”需要一次性通知所有窗口刷新。如果你不想给每个窗口都推还可以指定单个窗口的webContents发送按需控制。3.4 关于IPC安全能说的我都说了IPC在Electron里的地位相当于整个应用的心血管系统——只要它出了问题应用基本就瘫痪了。所以在设计IPC通信的时候我们还要考虑安全问题。我记得Electron的官方文档原话大意是不要把IPC接口做得“大而全”不要直接把ipcRenderer暴露给渲染进程。理想的做法是暴露一个语义明确的最小接口比如“读取文件的某个字段”“执行某个操作”而不是“给我任意路径的文件内容”。因为渲染进程的内容如果被XSS攻击攻击者拿到一个全能的IPC接口约等于拿到了能控制整个应用的开关。另外还有一个容易忽略的点主进程在ipcMain.handle里拿到外界传来的数据后一定要做验证不能直接当作可信输入使用。比如你要读取一个文件路径至少要判断路径的格式是否合法、是否在允许的目录内。我在项目里就吃过一次亏把路径直接拼进fs.readFile结果测试时传了个恶意路径读到的是完全无关的敏感配置内容。从那之后所有IPC入口的参数我都做了白名单校验。4. 菜单配置从系统默认菜单到自定义模板4.1 菜单到底归谁管当然是主进程菜单在Electron里分几种应用菜单最顶上那一栏Windows下在窗口标题栏下面macOS下在系统屏幕顶部、窗口上的右键菜单、还有托盘菜单。这些菜单全部由主进程的Menu模块来创建和管理渲染进程无法直接操作菜单。所以你要做自定义菜单第一步是确保你能在主进程代码里修改菜单配置而不是在Vue文件里找半天。最简单的菜单模板长这样const { Menu, app } require(electron) const template [ { label: 文件, submenu: [ { label: 打开文件, accelerator: CmdOrCtrlO, click: () { /* 处理打开文件逻辑 */ } }, { type: separator }, { label: 退出, role: quit } ] }, { label: 编辑, submenu: [ { role: undo, label: 撤销 }, { role: redo, label: 重做 }, { type: separator }, { role: cut, label: 剪切 }, { role: copy, label: 复制 }, { role: paste, label: 粘贴 } ] } ] const menu Menu.buildFromTemplate(template) Menu.setApplicationMenu(menu)关键点在于role这个字段。Electron内置了一批标准的菜单角色比如quit表示退出应用、copy表示复制、reload表示重新加载页面。直接指定roleElectron会帮你处理好对应的行为和快捷键不用自己写事件处理逻辑。这在开发初期能省不少事。4.2 菜单项点击之后调用IPC还是直接调用主进程功能菜单项的click回调运行在主进程里所以有两个选择。第一种是菜单项直接执行主进程的逻辑比如创建新窗口、打开文件对话框、退出应用。这种最直接不需要经过渲染进程。第二种是菜单项需要通知渲染进程比如“刷新当前页面数据”那就要在click回调里找到当前窗口的webContents然后通过webContents.send(refresh-data)通知渲染进程。这就是菜单和IPC联动的典型场景。{ label: 刷新数据, click: () { const win BrowserWindow.getFocusedWindow() win?.webContents.send(refresh-data) } }这里我强烈建议加一个空值判断。BrowserWindow.getFocusedWindow()是有可能返回null的比如用户聚焦在别的应用的窗口上时你在Electron里点击菜单项可能拿不到当前窗口。不加?.就直接调用send会直接抛TypeError。4.3 windows-95风格菜单其实是Electron的旧版外观搜热词时看到有同学在window 95 electron这个话题——这个其实说的是Electron窗口框架外观自定义。Electron本身没有内置“Windows 95皮肤”这种东西但它是支持自定义frame的。你可以创建无边框窗口frame: false然后自己用HTML/CSS/JS实现一套极简标题栏、菜单栏风格完全自定义。正因为Electron的界面层本质是Web页面理论上你想复刻任何年代的操作系统外观都不难。我自己就见过有人用Electron写了一个模拟Windows 95桌面的项目窗口、开始菜单、计算器全用前端代码画出来。如果你也想做类似的事情核心就两件事第一BrowserWindow创建时设置frame: false、titleBarStyle: hidden去掉系统默认边框第二自己实现窗口的拖动、最小化、关闭逻辑。拖动通过CSS属性-webkit-app-region: drag实现按钮区域则要设置成-webkit-app-region: no-drag否则按钮会点不动。5. 配置模板一套可以直接拿来改的项目骨架5.1 主进程模板从启动到窗口管理我平时新建项目时不会每次都从零敲代码而是维护了一套自己的模板文件。下面这套是最精简的、能跑通一个Vue项目的Electron主进程模板。// main.js const { app, BrowserWindow, ipcMain, Menu } require(electron) const path require(path) let mainWindow null function createMainWindow() { mainWindow new BrowserWindow({ width: 1280, height: 800, minWidth: 1024, minHeight: 700, autoHideMenuBar: false, webPreferences: { preload: path.join(__dirname, preload.js), contextIsolation: true, nodeIntegration: false, sandbox: true } }) const isDev !app.isPackaged if (isDev) { // 开发环境下加载 Vite 或 Webpack Dev Server mainWindow.loadURL(http://localhost:5173) mainWindow.webContents.openDevTools({ mode: detach }) } else { // 打包后加载本地文件 mainWindow.loadFile(path.join(__dirname, dist, index.html)) } mainWindow.on(closed, () { mainWindow null }) } app.whenReady().then(() { createMainWindow() // 注册菜单 setupMenu() // 注册 IPC 处理 registerIpcHandlers() app.on(activate, () { if (BrowserWindow.getAllWindows().length 0) createMainWindow() }) }) app.on(window-all-closed, () { if (process.platform ! darwin) { app.quit() } }) function setupMenu() { const template [ { label: 文件, submenu: [ { label: 退出, role: quit } ] } ] Menu.setApplicationMenu(Menu.buildFromTemplate(template)) } function registerIpcHandlers() { ipcMain.handle(get-app-version, () app.getVersion()) }几个关键点说明一下。isDev的判断用的是app.isPackaged这个属性在开发模式跑electron .下为false在打包安装后为true。前端构建工具的Dev Server地址在不同项目里不同Vite默认是http://localhost:5173Webpack通常配的是8080改一下就好。打包后loadFile的路径要注意__dirname是主进程文件所在目录如果你把index.html放在打包资源的根目录下这样写就是对的。5.2 预加载脚本模板安全暴露API这套模板是我从项目里抽出来的核心思路是把所有IPC通道包一层让渲染进程只认识语义化的方法。// preload.js const { contextBridge, ipcRenderer } require(electron) const validChannels [ window-minimize, window-maximize, window-close, get-app-version, refresh-data ] contextBridge.exposeInMainWorld(app, { minimize: () ipcRenderer.send(window-minimize), maximize: () ipcRenderer.send(window-maximize), close: () ipcRenderer.send(window-close), getVersion: () ipcRenderer.invoke(get-app-version), onRefresh: (callback) { const listener (_event, data) callback(data) ipcRenderer.on(refresh-data, listener) return () ipcRenderer.removeListener(refresh-data, listener) } })其中validChannels数组是我做校验用的实际生产环境里还可以把它加进监听逻辑防止渲染进程监听了预期之外的通道。onRefresh返回一个清理函数方便Vue组件在onUnmounted或者onBeforeUnmount里调用并注销监听避免组件卸载后回调仍然被触发造成内存泄漏或重复执行。5.3 渲染进程模板在Vue组件里使用公共API有了预加载脚本渲染进程里用起来就很简单了Vue组件里不用再关心“这是electron的东西”script setup import { onMounted, onUnmounted } from vue onMounted(() { const version await window.app.getVersion() console.log(当前应用版本, version) const unsubscribe window.app.onRefresh((data) { // 用 data 刷新页面 }) }) onUnmounted(() { // 别忘了调用 unsubscribe() }) /script5.4 模板背后的设计哲学隔离与解耦这套模板看起来普普通通但背后是我踩了不少坑之后才总结出的原则。第一渲染进程永远不直接出现ipcRenderer——因为一旦你在Vue代码里散落大量ipcRenderer.send后面想改通道名、想加权限校验就要翻遍整个前端代码。第二窗口控制和业务逻辑分开——窗口的最小化、最大化、关闭这种通用操作统一放在预加载层不要在渲染进程里直接用window.close()或者BrowserWindow配合奇奇怪怪的方式实现。第三通道名常量管理——如果项目大了通道名建议单独抽成一个常量文件主进程和预加载脚本共用避免手写字符串不一致。6. 打包实战Electron加Vue项目从开发到安装包6.1 为什么“开发能跑打包白屏”那么常见这是Electron社区里排得上号的经典问题。开发时一切正常npm run dev一执行窗口顺利打开页面显示完美结果npm run build加electron-builder打包完双击打开安装好的应用窗口是有了里面却一片惨白。这个现象九成以上是资源加载路径问题。开发阶段你用的是Dev Server的URL打包后应用要从文件系统加载本地HTML文件。如果你的前端代码里引用了绝对路径的静态资源比如/assets/app.js打包后文件协议下这个路径指向的是磁盘根目录自然找不到。解决办法很简单前端基路径改成相对路径。Vite项目在vite.config.js里设置base: ./Vue CLI项目设置publicPath: ./。这样打包出来的HTML里资源引用都是相对路径文件协议下就能正常工作。6.2 electron-builder配置模板我个人一直用electron-builder配置相对成熟社区文档也多。下面贴一份能用的最小配置放在package.json里或者独立的electron-builder.yml里appId: com.example.myapp productName: MyApp directories: output: release files: - dist/**/* - main.js - preload.js win: target: - nsis icon: build/icon.ico nsis: oneClick: false allowToChangeInstallationDirectory: true mac: target: - dmg category: public.app-category.productivity linux: target: - AppImage category: Utility几个经验之谈。第一files里面一定要包含dist目录和主进程、预加载脚本文件忘了加的话打包产物里根本没有这些文件应用启动直接找不到入口。第二Windows的图标必须是.ico格式如果只有PNG可以用工具转一下别因为图标问题卡住打包流程。第三NSIS配置里oneClick改成false是为了让用户能选安装目录如果你只想做免安装版改成portable目录或者用ziptarget也可以。6.3 打包后的额外操作主进程里的路径适配开发环境和打包环境的另一个大区别是路径。开发时__dirname指向的是你项目源码目录打包后它指向的是app.asar里面的解压目录。如果你在主进程里要读取某个配置文件千万别把路径写死要么用path.join(__dirname, ...)动态拼接要么用app.getPath(userData)去拿用户数据目录。// 推荐把运行时的临时数据放到用户目录 const userDataPath app.getPath(userData) const configPath path.join(userDataPath, config.json)这种做法的好处是用户数据不会被应用升级覆盖也不会因为权限问题写入失败。之前有同事把日志文件直接写到了__dirname下结果是每次升级程序日志就被抹掉用户一脸懵。后来我全部改到userData目录再没出过类似问题。7. 实战问答这些问题我都被问过或者亲身踩过7.1 窗口显示出来是白屏DevTools也打不开先说一个排查思路的优先级先确认打包后资源路径有没有问题看控制台报错再确认入口加载对不对最后怀疑依赖问题。我的习惯是打包之后如果白屏先用快捷键试着打开开发者工具一般CtrlShiftI如果能打开就看Console报错大部分情况下会看到一堆404那就是资源路径错了。如果是Failed to load resource: net::ERR_FILE_NOT_FOUND基本可以断定是base路径的问题。按前面的做法改成相对路径重新打包一次多半就好了。7.2Menu.setApplicationMenu(null)后快捷键失灵有同学为了界面简洁直接在主进程里执行Menu.setApplicationMenu(null)把菜单栏去掉结果发现CtrlC复制、CtrlV粘贴都失效了。原因在于系统菜单栏承载的不仅是菜单显示还绑定了一堆默认快捷键行为。你把它整个干掉编辑类快捷键一起没了。想保留快捷键又不想要菜单栏最优雅的方式是用Menu.buildFromTemplate构建一个空模板然后设置给应用模板里只保留编辑相关的role子菜单或者用globalShortcut手动注册快捷键。但后者会失去对页面焦点状态的感知某些场景反而不如前者好用。7.3 IPC的ipcMain.on注册了两遍导致消息重复处理这个问题很隐蔽。如果你在主进程的模块里不小心把某个on处理器的注册代码写在模块顶层而这个模块被多处require监听器就可能被重复注册。结果就是渲染进程发一条消息主进程处理两次返回值错乱、状态错乱各种怪问题。建议统一的写法把IPC注册函数集中在主进程入口代码里只在app.whenReady()之后调用一次并且多用ipcMain.handle代替ipcMain.on。因为handle在同一通道上重复注册会直接抛错你能第一时间发现重复注册问题而不是被“处理了两遍”这种诡异行为坑半天。7.4 点击Electron打包的安装包没反应有些双击安装包之后毫无反应既没有窗口也没有报错。先检查目录里是不是有中文字符路径electron-builder在某些版本对中文路径处理有历史遗留问题再检查杀毒软件是否拦截了生成的可执行文件最后看任务管理器里有没有进程残留。注意这个优先级从常见到不常见排列90%的情况出在前两个。7.5 Vue项目里用require(electron)直接报错还记得前面说的预加载脚本方案吗如果你混用旧式写法在渲染进程里require(electron)会得到Uncaught ReferenceError: require is not defined。如果你特别想用这种方式唯一的办法是创建窗口时把nodeIntegration设为true并关闭contextIsolation。但我不推荐。安全模型一旦放松后面的坑会一个接着一个。你的界面逻辑、用户输入、第三方依赖都是渲染进程里的执行内容它们能拿到Node权限之后任何一个XSS漏洞都可能变成系统级漏洞。7.6 多窗口之间共享数据怎么做小型项目用全局变量就够——主进程维护一个对象窗口A通过IPC通知主进程更新状态窗口B通过IPC查询状态。到项目规模变大后我建议用主进程里订阅发布模式管理状态或者如果你依赖了Vue可以让所有渲染进程用同一套状态管理库通过IPC同步数据。注意千万别直接从窗口A的渲染进程里去操作窗口B的DOM进程隔离不允许Electron的设计也不鼓励。8. 关于性能优化和内存管理我的一些亲身教训8.1 给大列表应用开webPreferences的坑如果你的应用是那种表格控件、大量DOM节点的管理后台默认的webPreferences配置下滚动可能会有一点卡顿。我试过把webPreferences里的backgroundThrottling设为false禁止后台节流对某些动画场景有改善但代价是窗口最小化时仍保持高CPU占用。这个开关要慎重不是所有App都需要。更实际的做法是尽量把大数据渲染放在虚拟滚动控件上减少实际DOM数量图像资源做懒加载和压缩别在渲染进程里跑死循环似的组件更新逻辑。Electron再快也扛不住DOM节点几百上千的数量级乱堆。8.2 监听器和定时器的清理这个坑几乎每个Electron开发者都会踩到一次。在渲染进程里反复进入页面、退出页面如果监听器注册了没注销定时器启动了没清理进程占用的内存就会一步步涨上去最终表现为“用着用着应用越来越卡”。我的清理规范很简单所有ipcRenderer.on注册的回调必须对应一个removeListener调用所有setInterval必须有对应的clearInterval。在Vue组件里这两个操作分别放在onMounted和onBeforeUnmount里。看起来是基本功但很多项目收尾时就是漏了这个导致线上用户反馈内存占用高得离谱。8.3 监控渲染进程崩溃Electron应用进程多了就不能忽视崩溃恢复。监听渲染进程的render-process-gone事件是官方推荐的姿势——它会在渲染进程异常退出时触发回调里能拿到崩溃原因。mainWindow.webContents.on(render-process-gone, (_event, details) { if (details.reason crashed) { // 记录日志并且可以弹窗提示用户刷新页面 mainWindow.reload() } })这里要注意details.reason可能的值有好几个clean-exit正常退出、abnormal-exit异常退出、crashed崩溃、launch-failed启动失败、oom内存不足。对不同原因处理策略也该区分oom你立刻reload可能还会继续崩不如提示用户关闭多余页面再试。9. 从Electron到鸿蒙适配的思考搜热词的时候看到Electron应用移植鸿蒙教程这类话题有一定热度。我专门去了解了一下这部分不是Electron官方能力而是国内一些方案在做“把Electron应用跑到鸿蒙系统上”的适配。方向上有两类思路一类是把Electron应用里的业务代码尽量保持前后端分离界面层用标准Web技术系统能力通过抽象层调用这样换平台时只替换壳层另一类是直接在鸿蒙侧用方舟运行时之类的技术按鸿蒙的开发规范去重写壳层业务Web内容复用起来。这件事给我的启发是哪怕暂时没有鸿蒙适配需求Electron项目的架构设计也应该往“主进程功能薄、渲染进程业务纯、系统能力抽象化”的方向靠。不要把太多系统调用散落在各个模块里后面哪天要换壳、要移植、要嵌入别的WebView容器你会感谢当时那份“看起来多做了一步”的封装。10. 最后分享几个我压箱底的实用习惯先说开发调试的事。我一般会在主进程启动时判断环境变量只有开发模式才自动打开DevTools。process.env.NODE_ENV development或者!app.isPackaged都可以别打包上线之后自动给用户弹一个开发者工具那画面太美。再说日志。Electron应用的日志别只打在控制台里。生产环境建议用electron-log这个库或者自己写一个精简的日志模块把主进程的关键事件写到userData目录。这样用户反馈问题的时候你能拿到主进程日志排查而不是靠猜。接着是快捷键。如果你要做全局快捷键应用不在前台时也能响应用globalShortcut模块。但注意全局快捷键是系统级的很容易和用户其他软件冲突注册前给用户留自定义入口这是一个基本礼仪。还有代码签名。Windows下如果不做签名打包出的exe在SmartScreen会触发蓝色警告弹窗用户需要多点一次“仍要运行”。个人开发者做这个比较麻烦但如果你是公司内部工具建议至少配置一个证书。macOS同理没签名基本很难发布给普通用户。最后说句掏心窝的话Electron的入门门槛确实不高Web开发者几乎可以无缝上手。但真正决定项目上线后体验的往往是安全配置、内存管理、崩溃恢复这些“看不见”的部分。这也是为什么我坚持在博文里把这些细节全部拿出来讲——因为这些东西官方文档不会替你总结只有项目做到后期才能真正体会到它们的分量。希望这份速查手册和模板能帮你少走几步弯路。
Electron开发速查手册：主进程、IPC通信与打包实战
写Electron这块的内容其实我早就想动手了。前后折腾了好几个项目——从给内部做的桌面运维小工具到把一套Vue管理后台完整封装成客户端再到后面帮同事排查那种“打包完就白屏”的玄学问题。Electron这个东西说简单是真简单一个浏览器壳子套上Node能力HTML页面摇身一变就成了桌面应用但说复杂也真复杂主进程、渲染进程、预加载脚本、IPC通信、菜单、打包配置任何一个环节没理清楚项目一大了就开始到处漏风。这篇速查手册就是基于我实际踩坑经验整理出来的把最常碰到的配置、模板、坑点都放在一起。这篇内容适合两类人看一是刚接触Electron、想搞清楚主进程和渲染进程到底怎么回事的新手二是已经上手但每次写IPC、调菜单、打包都要翻文档老半天的“熟练工”。看完你至少能直接拿走一套能跑的模板然后照着改。1. 为什么桌面应用开发绕不开Electron1.1 Electron到底解决了什么问题先说个直观的对比。过去要做桌面软件Windows上多半是C#配WinForms或WPFmacOS上是Swift配AppKitLinux更是各发行版各玩各的。你花大力气写完一套界面换个系统基本等于重写。更别提界面这件事本身就不是后端开发者的强项——写个表单、调个布局、处理个焦点事件能磨掉你半天心态。Electron的核心思路就是“用Web技术栈做桌面应用”。它把Chromium浏览器的渲染引擎和Node.js服务端运行环境打包在一起让你能用HTML、CSS、JavaScript去构建桌面客户端。同一套代码Windows能跑、macOS能跑、Linux也能跑顶多打包和适配的时候各自调一调。这个价值在团队里如果正好有前端工程师的情况下尤其明显前端同学不用从头学C或者C#后端同学也不用硬啃GUI框架的文档。我自己的体会是Electron最适合那类“管理系统”“数据看板”“内部工具”的项目。这类需求的特点是要展示大量表格、图表、表单交互逻辑集中在页面上同时又希望它有独立窗口、能访问本地文件系统而不是纯粹开个浏览器输地址。Electron恰好把这些都覆盖了窗口归Electron管页面交互归Web技术管本地能力归Node管。1.2 什么情况下要慎重选它当然Electron也不是万能钥匙。最典型的负面印象是“包体积大”——一个最简单的应用装上Electron打包出来少说一百多兆。这是因为里面塞了一个完整的Chromium。另外就是内存占用每个窗口对应一个渲染进程开三四个窗口内存分分钟上去。你要是做一个常驻后台、对资源极其敏感的小工具Electron不一定是最优解Tauri这类用系统WebView的方案会更轻。还有一个容易被忽视的点如果你的核心逻辑是重CPU计算、图像处理、音视频编解码这类活儿Electron的JS生态做起来会比较吃力。不是说做不了而是性能和那种底层语言写出来的差距比较明显。这种情况我更建议把重活儿拆成独立的原生模块或者子进程让Electron只负责界面调度。我的建议是项目规模中等、团队以Web技术为主、跨平台是硬需求、交付周期又紧——选Electron没毛病。反过来说如果你有极端的包体积要求、内存敏感、或者核心逻辑完全绕不开底层API——建议三思。2. 开篇第一课主进程和渲染进程到底怎么分工2.1 主进程到底是干什么的Electron应用启动后第一个被创建的是主进程。它运行在Node.js环境中拥有完整的Node能力——读写文件、访问网络、使用操作系统API都可以直接做。主进程的生命周期是整个应用的生命周期应用启动它启动应用退出它退出。它也是整个应用的“调度中心”所有原生窗口的创建、关闭、最小化包括后续讲到的应用菜单、系统托盘、对话框都是由主进程来管的。一个最直观的例子是创建窗口。你在主进程里调用new BrowserWindow()Electron才去创建一个新的窗口。窗口里的内容是什么加载一个远程URL或者加载本地打包好的HTML文件都由主进程决定。2.2 渲染进程又是怎么回事每个BrowserWindow实例都会开启一个独立的渲染进程。这个进程可以理解成“一个跑在Chromium里的网页”的环境你熟悉的DOM操作、CSS布局、浏览器API在这里都是可用的。渲染进程里你可以正常写Vue、写React和平时做网页开发几乎没区别。整个架构可以简单理解成主进程是老板负责申请资源、创建窗口、对接系统能力渲染进程是员工负责把页面内容画出来、和用户交互。老板和员工是隔离的——渲染进程不能直接碰Node的API主进程也不直接碰用户的点击事件。这个隔离是刻意的安全设计Electron的文档里反复强调“渲染进程不可信”因为渲染进程加载的内容如果来自网络理论上可能被注入恶意脚本。2.3 新手最容易犯的错在渲染进程里直接写Node代码这块我必须多写几句因为我见过太多人在这个点上栽跟头。有人直接在Vue组件里写上const fs require(fs) fs.readFileSync(/path/to/file)然后跑起来发现require is not defined或者直接白屏。原因很简单默认情况下渲染进程的nodeIntegration是关闭的。这是Electron从安全角度考虑的默认选项——一旦打开页面上任何被执行的脚本都能拿到Node的全部能力这等于把整个系统权限暴露给了页面。所以你在渲染进程里不能直接用require因为你压根在浏览器环境的沙箱里。正确的做法是把需要Node能力的事情交给主进程用IPC机制来回传数据。这个我会在下一节展开。关于这部分的架构关系我用一张表帮你快速理解维度主进程渲染进程运行环境Node.jsChromium浏览器环境核心能力窗口管理、系统API、文件、网络DOM、CSS、页面渲染能否用DOM不能能能否直接读写文件能默认不能数量一个每个窗口一个关闭影响应用退出仅关闭当前窗口3. IPC通信Electron开发的核心必修课3.1 从ipcMain和ipcRenderer这两个“信使”说起IPC全称是Inter-Process Communication也就是进程间通信。在Electron里主进程和渲染进程之间的所有消息传递都要走IPC。Electron为这个机制提供了一对核心模块ipcMain和ipcRenderer。ipcMain注册在主进程里负责接收来自渲染进程的消息并处理ipcRenderer注册在渲染进程里负责发消息和接收主进程的回复。最基础的用法是“渲染进程发主进程收”。渲染进程里这样写// 渲染进程 const { ipcRenderer } require(electron) ipcRenderer.send(window-minimize)主进程里这样写// 主进程 const { ipcMain, BrowserWindow } require(electron) ipcMain.on(window-minimize, (event) { const win BrowserWindow.fromWebContents(event.sender) win.minimize() })这里面有两点值得注意。第一event.sender是一个webContents对象它指代“发消息的那个窗口”主进程可以通过它拿到对应的BrowserWindow实例第二消息通道名称这里是window-minimize两端必须完全一致否则消息就石沉大海。3.2 遇到ipcRenderer is not defined怎么办这里有一个很现实的问题现在的项目基本都是脚手架生成的前端工程渲染进程用Vue或者React构建。如果你直接在前端代码里写require(electron)大概率会碰到ipcRenderer is not defined。原因在于渲染进程默认是禁用了Node集成的同时前端的构建工具Webpack、Vite环境里也没有Electron的模块机制。在这个前提下你直接引入electron模块编译阶段可能不报错但运行时拿不到ipcRenderer对象。最稳妥、也是Electron官方推荐的解法是为渲染进程配置一个“预加载脚本”在脚本里用contextBridge暴露一个安全的接口给渲染进程。具体这么做// preload.js const { contextBridge, ipcRenderer } require(electron) contextBridge.exposeInMainWorld(electronAPI, { minimize: () ipcRenderer.send(window-minimize), onUpdate: (callback) { ipcRenderer.on(update-message, (_event, data) callback(data)) } })然后在主进程创建窗口时指定预加载脚本const win new BrowserWindow({ width: 1200, height: 800, webPreferences: { preload: path.join(__dirname, preload.js), contextIsolation: true, nodeIntegration: false } })这样在渲染进程的Vue组件里你就能直接调用window.electronAPI.minimize()而完全不需要关心底层的IPC细节。这个模式的好处是渲染进程始终只接触你暴露出的一小撮方法拿不到完整的Electron能力安全性和可维护性都更高。3.3 单向通信、双向通信、广播三种场景分别怎么写实际开发中你很快会发现光靠send和on还不能覆盖所有场景。有些时候你需要“问一句、答一句”双向通信有些时候主进程要主动给所有窗口推消息广播。下面我把三种模式都列出来方便你照着抄。单向通信渲染进程发给主进程主进程不回复// 渲染进程 ipcRenderer.send(log-message, user clicked button) // 主进程 ipcMain.on(log-message, (_event, message) { console.log(message) })双向通信渲染进程发消息主进程处理完再回复渲染进程侧用invoke发送并接收一个Promiseconst result await window.electronAPI.getFileContent(/path/to/file)主进程侧用ipcMain.handle来处理ipcMain.handle(get-file-content, async (_event, filePath) { const content await fs.promises.readFile(filePath, utf-8) return content })invoke/handle这对组合是我在项目里用得最多的原因很直接它天然支持异步而且在渲染进程侧写法最接近普通的函数调用——不用注册监听器不用管理事件销毁拿到返回结果就是await一下的事。主进程广播向所有打开的窗口推送消息BrowserWindow.getAllWindows().forEach(win { win.webContents.send(data-refreshed, newData) })渲染进程侧照常监听window.electronAPI.onDataRefreshed((data) { // 更新页面数据 })广播场景最典型的就是“主进程在后台检测到文件变化/网络状态变化/数据更新”需要一次性通知所有窗口刷新。如果你不想给每个窗口都推还可以指定单个窗口的webContents发送按需控制。3.4 关于IPC安全能说的我都说了IPC在Electron里的地位相当于整个应用的心血管系统——只要它出了问题应用基本就瘫痪了。所以在设计IPC通信的时候我们还要考虑安全问题。我记得Electron的官方文档原话大意是不要把IPC接口做得“大而全”不要直接把ipcRenderer暴露给渲染进程。理想的做法是暴露一个语义明确的最小接口比如“读取文件的某个字段”“执行某个操作”而不是“给我任意路径的文件内容”。因为渲染进程的内容如果被XSS攻击攻击者拿到一个全能的IPC接口约等于拿到了能控制整个应用的开关。另外还有一个容易忽略的点主进程在ipcMain.handle里拿到外界传来的数据后一定要做验证不能直接当作可信输入使用。比如你要读取一个文件路径至少要判断路径的格式是否合法、是否在允许的目录内。我在项目里就吃过一次亏把路径直接拼进fs.readFile结果测试时传了个恶意路径读到的是完全无关的敏感配置内容。从那之后所有IPC入口的参数我都做了白名单校验。4. 菜单配置从系统默认菜单到自定义模板4.1 菜单到底归谁管当然是主进程菜单在Electron里分几种应用菜单最顶上那一栏Windows下在窗口标题栏下面macOS下在系统屏幕顶部、窗口上的右键菜单、还有托盘菜单。这些菜单全部由主进程的Menu模块来创建和管理渲染进程无法直接操作菜单。所以你要做自定义菜单第一步是确保你能在主进程代码里修改菜单配置而不是在Vue文件里找半天。最简单的菜单模板长这样const { Menu, app } require(electron) const template [ { label: 文件, submenu: [ { label: 打开文件, accelerator: CmdOrCtrlO, click: () { /* 处理打开文件逻辑 */ } }, { type: separator }, { label: 退出, role: quit } ] }, { label: 编辑, submenu: [ { role: undo, label: 撤销 }, { role: redo, label: 重做 }, { type: separator }, { role: cut, label: 剪切 }, { role: copy, label: 复制 }, { role: paste, label: 粘贴 } ] } ] const menu Menu.buildFromTemplate(template) Menu.setApplicationMenu(menu)关键点在于role这个字段。Electron内置了一批标准的菜单角色比如quit表示退出应用、copy表示复制、reload表示重新加载页面。直接指定roleElectron会帮你处理好对应的行为和快捷键不用自己写事件处理逻辑。这在开发初期能省不少事。4.2 菜单项点击之后调用IPC还是直接调用主进程功能菜单项的click回调运行在主进程里所以有两个选择。第一种是菜单项直接执行主进程的逻辑比如创建新窗口、打开文件对话框、退出应用。这种最直接不需要经过渲染进程。第二种是菜单项需要通知渲染进程比如“刷新当前页面数据”那就要在click回调里找到当前窗口的webContents然后通过webContents.send(refresh-data)通知渲染进程。这就是菜单和IPC联动的典型场景。{ label: 刷新数据, click: () { const win BrowserWindow.getFocusedWindow() win?.webContents.send(refresh-data) } }这里我强烈建议加一个空值判断。BrowserWindow.getFocusedWindow()是有可能返回null的比如用户聚焦在别的应用的窗口上时你在Electron里点击菜单项可能拿不到当前窗口。不加?.就直接调用send会直接抛TypeError。4.3 windows-95风格菜单其实是Electron的旧版外观搜热词时看到有同学在window 95 electron这个话题——这个其实说的是Electron窗口框架外观自定义。Electron本身没有内置“Windows 95皮肤”这种东西但它是支持自定义frame的。你可以创建无边框窗口frame: false然后自己用HTML/CSS/JS实现一套极简标题栏、菜单栏风格完全自定义。正因为Electron的界面层本质是Web页面理论上你想复刻任何年代的操作系统外观都不难。我自己就见过有人用Electron写了一个模拟Windows 95桌面的项目窗口、开始菜单、计算器全用前端代码画出来。如果你也想做类似的事情核心就两件事第一BrowserWindow创建时设置frame: false、titleBarStyle: hidden去掉系统默认边框第二自己实现窗口的拖动、最小化、关闭逻辑。拖动通过CSS属性-webkit-app-region: drag实现按钮区域则要设置成-webkit-app-region: no-drag否则按钮会点不动。5. 配置模板一套可以直接拿来改的项目骨架5.1 主进程模板从启动到窗口管理我平时新建项目时不会每次都从零敲代码而是维护了一套自己的模板文件。下面这套是最精简的、能跑通一个Vue项目的Electron主进程模板。// main.js const { app, BrowserWindow, ipcMain, Menu } require(electron) const path require(path) let mainWindow null function createMainWindow() { mainWindow new BrowserWindow({ width: 1280, height: 800, minWidth: 1024, minHeight: 700, autoHideMenuBar: false, webPreferences: { preload: path.join(__dirname, preload.js), contextIsolation: true, nodeIntegration: false, sandbox: true } }) const isDev !app.isPackaged if (isDev) { // 开发环境下加载 Vite 或 Webpack Dev Server mainWindow.loadURL(http://localhost:5173) mainWindow.webContents.openDevTools({ mode: detach }) } else { // 打包后加载本地文件 mainWindow.loadFile(path.join(__dirname, dist, index.html)) } mainWindow.on(closed, () { mainWindow null }) } app.whenReady().then(() { createMainWindow() // 注册菜单 setupMenu() // 注册 IPC 处理 registerIpcHandlers() app.on(activate, () { if (BrowserWindow.getAllWindows().length 0) createMainWindow() }) }) app.on(window-all-closed, () { if (process.platform ! darwin) { app.quit() } }) function setupMenu() { const template [ { label: 文件, submenu: [ { label: 退出, role: quit } ] } ] Menu.setApplicationMenu(Menu.buildFromTemplate(template)) } function registerIpcHandlers() { ipcMain.handle(get-app-version, () app.getVersion()) }几个关键点说明一下。isDev的判断用的是app.isPackaged这个属性在开发模式跑electron .下为false在打包安装后为true。前端构建工具的Dev Server地址在不同项目里不同Vite默认是http://localhost:5173Webpack通常配的是8080改一下就好。打包后loadFile的路径要注意__dirname是主进程文件所在目录如果你把index.html放在打包资源的根目录下这样写就是对的。5.2 预加载脚本模板安全暴露API这套模板是我从项目里抽出来的核心思路是把所有IPC通道包一层让渲染进程只认识语义化的方法。// preload.js const { contextBridge, ipcRenderer } require(electron) const validChannels [ window-minimize, window-maximize, window-close, get-app-version, refresh-data ] contextBridge.exposeInMainWorld(app, { minimize: () ipcRenderer.send(window-minimize), maximize: () ipcRenderer.send(window-maximize), close: () ipcRenderer.send(window-close), getVersion: () ipcRenderer.invoke(get-app-version), onRefresh: (callback) { const listener (_event, data) callback(data) ipcRenderer.on(refresh-data, listener) return () ipcRenderer.removeListener(refresh-data, listener) } })其中validChannels数组是我做校验用的实际生产环境里还可以把它加进监听逻辑防止渲染进程监听了预期之外的通道。onRefresh返回一个清理函数方便Vue组件在onUnmounted或者onBeforeUnmount里调用并注销监听避免组件卸载后回调仍然被触发造成内存泄漏或重复执行。5.3 渲染进程模板在Vue组件里使用公共API有了预加载脚本渲染进程里用起来就很简单了Vue组件里不用再关心“这是electron的东西”script setup import { onMounted, onUnmounted } from vue onMounted(() { const version await window.app.getVersion() console.log(当前应用版本, version) const unsubscribe window.app.onRefresh((data) { // 用 data 刷新页面 }) }) onUnmounted(() { // 别忘了调用 unsubscribe() }) /script5.4 模板背后的设计哲学隔离与解耦这套模板看起来普普通通但背后是我踩了不少坑之后才总结出的原则。第一渲染进程永远不直接出现ipcRenderer——因为一旦你在Vue代码里散落大量ipcRenderer.send后面想改通道名、想加权限校验就要翻遍整个前端代码。第二窗口控制和业务逻辑分开——窗口的最小化、最大化、关闭这种通用操作统一放在预加载层不要在渲染进程里直接用window.close()或者BrowserWindow配合奇奇怪怪的方式实现。第三通道名常量管理——如果项目大了通道名建议单独抽成一个常量文件主进程和预加载脚本共用避免手写字符串不一致。6. 打包实战Electron加Vue项目从开发到安装包6.1 为什么“开发能跑打包白屏”那么常见这是Electron社区里排得上号的经典问题。开发时一切正常npm run dev一执行窗口顺利打开页面显示完美结果npm run build加electron-builder打包完双击打开安装好的应用窗口是有了里面却一片惨白。这个现象九成以上是资源加载路径问题。开发阶段你用的是Dev Server的URL打包后应用要从文件系统加载本地HTML文件。如果你的前端代码里引用了绝对路径的静态资源比如/assets/app.js打包后文件协议下这个路径指向的是磁盘根目录自然找不到。解决办法很简单前端基路径改成相对路径。Vite项目在vite.config.js里设置base: ./Vue CLI项目设置publicPath: ./。这样打包出来的HTML里资源引用都是相对路径文件协议下就能正常工作。6.2 electron-builder配置模板我个人一直用electron-builder配置相对成熟社区文档也多。下面贴一份能用的最小配置放在package.json里或者独立的electron-builder.yml里appId: com.example.myapp productName: MyApp directories: output: release files: - dist/**/* - main.js - preload.js win: target: - nsis icon: build/icon.ico nsis: oneClick: false allowToChangeInstallationDirectory: true mac: target: - dmg category: public.app-category.productivity linux: target: - AppImage category: Utility几个经验之谈。第一files里面一定要包含dist目录和主进程、预加载脚本文件忘了加的话打包产物里根本没有这些文件应用启动直接找不到入口。第二Windows的图标必须是.ico格式如果只有PNG可以用工具转一下别因为图标问题卡住打包流程。第三NSIS配置里oneClick改成false是为了让用户能选安装目录如果你只想做免安装版改成portable目录或者用ziptarget也可以。6.3 打包后的额外操作主进程里的路径适配开发环境和打包环境的另一个大区别是路径。开发时__dirname指向的是你项目源码目录打包后它指向的是app.asar里面的解压目录。如果你在主进程里要读取某个配置文件千万别把路径写死要么用path.join(__dirname, ...)动态拼接要么用app.getPath(userData)去拿用户数据目录。// 推荐把运行时的临时数据放到用户目录 const userDataPath app.getPath(userData) const configPath path.join(userDataPath, config.json)这种做法的好处是用户数据不会被应用升级覆盖也不会因为权限问题写入失败。之前有同事把日志文件直接写到了__dirname下结果是每次升级程序日志就被抹掉用户一脸懵。后来我全部改到userData目录再没出过类似问题。7. 实战问答这些问题我都被问过或者亲身踩过7.1 窗口显示出来是白屏DevTools也打不开先说一个排查思路的优先级先确认打包后资源路径有没有问题看控制台报错再确认入口加载对不对最后怀疑依赖问题。我的习惯是打包之后如果白屏先用快捷键试着打开开发者工具一般CtrlShiftI如果能打开就看Console报错大部分情况下会看到一堆404那就是资源路径错了。如果是Failed to load resource: net::ERR_FILE_NOT_FOUND基本可以断定是base路径的问题。按前面的做法改成相对路径重新打包一次多半就好了。7.2Menu.setApplicationMenu(null)后快捷键失灵有同学为了界面简洁直接在主进程里执行Menu.setApplicationMenu(null)把菜单栏去掉结果发现CtrlC复制、CtrlV粘贴都失效了。原因在于系统菜单栏承载的不仅是菜单显示还绑定了一堆默认快捷键行为。你把它整个干掉编辑类快捷键一起没了。想保留快捷键又不想要菜单栏最优雅的方式是用Menu.buildFromTemplate构建一个空模板然后设置给应用模板里只保留编辑相关的role子菜单或者用globalShortcut手动注册快捷键。但后者会失去对页面焦点状态的感知某些场景反而不如前者好用。7.3 IPC的ipcMain.on注册了两遍导致消息重复处理这个问题很隐蔽。如果你在主进程的模块里不小心把某个on处理器的注册代码写在模块顶层而这个模块被多处require监听器就可能被重复注册。结果就是渲染进程发一条消息主进程处理两次返回值错乱、状态错乱各种怪问题。建议统一的写法把IPC注册函数集中在主进程入口代码里只在app.whenReady()之后调用一次并且多用ipcMain.handle代替ipcMain.on。因为handle在同一通道上重复注册会直接抛错你能第一时间发现重复注册问题而不是被“处理了两遍”这种诡异行为坑半天。7.4 点击Electron打包的安装包没反应有些双击安装包之后毫无反应既没有窗口也没有报错。先检查目录里是不是有中文字符路径electron-builder在某些版本对中文路径处理有历史遗留问题再检查杀毒软件是否拦截了生成的可执行文件最后看任务管理器里有没有进程残留。注意这个优先级从常见到不常见排列90%的情况出在前两个。7.5 Vue项目里用require(electron)直接报错还记得前面说的预加载脚本方案吗如果你混用旧式写法在渲染进程里require(electron)会得到Uncaught ReferenceError: require is not defined。如果你特别想用这种方式唯一的办法是创建窗口时把nodeIntegration设为true并关闭contextIsolation。但我不推荐。安全模型一旦放松后面的坑会一个接着一个。你的界面逻辑、用户输入、第三方依赖都是渲染进程里的执行内容它们能拿到Node权限之后任何一个XSS漏洞都可能变成系统级漏洞。7.6 多窗口之间共享数据怎么做小型项目用全局变量就够——主进程维护一个对象窗口A通过IPC通知主进程更新状态窗口B通过IPC查询状态。到项目规模变大后我建议用主进程里订阅发布模式管理状态或者如果你依赖了Vue可以让所有渲染进程用同一套状态管理库通过IPC同步数据。注意千万别直接从窗口A的渲染进程里去操作窗口B的DOM进程隔离不允许Electron的设计也不鼓励。8. 关于性能优化和内存管理我的一些亲身教训8.1 给大列表应用开webPreferences的坑如果你的应用是那种表格控件、大量DOM节点的管理后台默认的webPreferences配置下滚动可能会有一点卡顿。我试过把webPreferences里的backgroundThrottling设为false禁止后台节流对某些动画场景有改善但代价是窗口最小化时仍保持高CPU占用。这个开关要慎重不是所有App都需要。更实际的做法是尽量把大数据渲染放在虚拟滚动控件上减少实际DOM数量图像资源做懒加载和压缩别在渲染进程里跑死循环似的组件更新逻辑。Electron再快也扛不住DOM节点几百上千的数量级乱堆。8.2 监听器和定时器的清理这个坑几乎每个Electron开发者都会踩到一次。在渲染进程里反复进入页面、退出页面如果监听器注册了没注销定时器启动了没清理进程占用的内存就会一步步涨上去最终表现为“用着用着应用越来越卡”。我的清理规范很简单所有ipcRenderer.on注册的回调必须对应一个removeListener调用所有setInterval必须有对应的clearInterval。在Vue组件里这两个操作分别放在onMounted和onBeforeUnmount里。看起来是基本功但很多项目收尾时就是漏了这个导致线上用户反馈内存占用高得离谱。8.3 监控渲染进程崩溃Electron应用进程多了就不能忽视崩溃恢复。监听渲染进程的render-process-gone事件是官方推荐的姿势——它会在渲染进程异常退出时触发回调里能拿到崩溃原因。mainWindow.webContents.on(render-process-gone, (_event, details) { if (details.reason crashed) { // 记录日志并且可以弹窗提示用户刷新页面 mainWindow.reload() } })这里要注意details.reason可能的值有好几个clean-exit正常退出、abnormal-exit异常退出、crashed崩溃、launch-failed启动失败、oom内存不足。对不同原因处理策略也该区分oom你立刻reload可能还会继续崩不如提示用户关闭多余页面再试。9. 从Electron到鸿蒙适配的思考搜热词的时候看到Electron应用移植鸿蒙教程这类话题有一定热度。我专门去了解了一下这部分不是Electron官方能力而是国内一些方案在做“把Electron应用跑到鸿蒙系统上”的适配。方向上有两类思路一类是把Electron应用里的业务代码尽量保持前后端分离界面层用标准Web技术系统能力通过抽象层调用这样换平台时只替换壳层另一类是直接在鸿蒙侧用方舟运行时之类的技术按鸿蒙的开发规范去重写壳层业务Web内容复用起来。这件事给我的启发是哪怕暂时没有鸿蒙适配需求Electron项目的架构设计也应该往“主进程功能薄、渲染进程业务纯、系统能力抽象化”的方向靠。不要把太多系统调用散落在各个模块里后面哪天要换壳、要移植、要嵌入别的WebView容器你会感谢当时那份“看起来多做了一步”的封装。10. 最后分享几个我压箱底的实用习惯先说开发调试的事。我一般会在主进程启动时判断环境变量只有开发模式才自动打开DevTools。process.env.NODE_ENV development或者!app.isPackaged都可以别打包上线之后自动给用户弹一个开发者工具那画面太美。再说日志。Electron应用的日志别只打在控制台里。生产环境建议用electron-log这个库或者自己写一个精简的日志模块把主进程的关键事件写到userData目录。这样用户反馈问题的时候你能拿到主进程日志排查而不是靠猜。接着是快捷键。如果你要做全局快捷键应用不在前台时也能响应用globalShortcut模块。但注意全局快捷键是系统级的很容易和用户其他软件冲突注册前给用户留自定义入口这是一个基本礼仪。还有代码签名。Windows下如果不做签名打包出的exe在SmartScreen会触发蓝色警告弹窗用户需要多点一次“仍要运行”。个人开发者做这个比较麻烦但如果你是公司内部工具建议至少配置一个证书。macOS同理没签名基本很难发布给普通用户。最后说句掏心窝的话Electron的入门门槛确实不高Web开发者几乎可以无缝上手。但真正决定项目上线后体验的往往是安全配置、内存管理、崩溃恢复这些“看不见”的部分。这也是为什么我坚持在博文里把这些细节全部拿出来讲——因为这些东西官方文档不会替你总结只有项目做到后期才能真正体会到它们的分量。希望这份速查手册和模板能帮你少走几步弯路。
