做了几年 Electron 桌面应用踩过的坑凑起来能写一本书。很多人上手 Electron 都从“能跑起来”开始但真正到了要上生产、要打包、要处理原生能力的时候才会发现文档之外全是细节。这篇东西不是入门教程而是把 Electron 开发里那些“很关键但容易被忽略”的核心要点补一遍——技术栈选型、localhost 本地联调、菜单体系、应用内购买、打包分发每一块我都用实际项目中验证过的方案来讲。适合正在做 Electron 的朋友也适合准备用 Electron 重构或立项的团队读的时候直接对照自己的项目排查就行。1. 技术栈全貌先搞清楚 Electron 到底站在什么位置1.1 Chromium、Node.js 和原生模块三个世界的交汇Electron 本质上是一个拼装方案用 Chromium 负责界面渲染用 Node.js 提供本地能力再用一套原生接口把两者缝合起来。所以你写的应用同时跑在三个世界里这一点必须从一开始就记死。主进程Main Process是最容易被忽视的。它是 Node.js 环境负责创建窗口、管理生命周期、访问文件系统、调用系统能力。渲染进程Renderer Process每个窗口一个本质上就是一个浏览器标签页跑着你的 HTML/CSS/JavaScript页面里的window、document、fetch都好使但你不能直接在主进程里写 DOM也不能在渲染进程里直接调 Node.js 的fs——除非你设置了nodeIntegration: true但我强烈建议不要开。这两个进程之间靠 IPC 通信而预加载脚本Preload Script则是安全地暴露 API 给渲染进程的桥梁。我见过太多初学者的项目把nodeIntegration一开到底风险非常大。给页面的能力应该越少越好只通过contextBridge暴露特定的方法比如window.electronAPI.readFile这样即使页面被注入恶意内容攻击面也被限制住了。记住一句经验把主进程当后端把渲染进程当前端把 preload 当网关整个应用的架构就清晰了。1.2 用 Electron 之前必须想清楚的三件事Electron 不是银弹立项前一定要先确认三个问题包体积、内存占用和维护成本。一个最简 Electron 应用打包出来随便 80MB 起步因为塞了完整 Chromium。内存占用通常也在 200MB 上下运行多个窗口还会更高。如果你做的是一个后台工具软件目标用户设备很老那这一套可能就不合适。替代方案里Tauri 是热度最高的它用系统 WebView 加 Rust 后端包体积能压到十几 MB但代价是你得把主进程逻辑用 Rust 重写而且对系统 WebView 版本的兼容需要额外处理。如果团队是纯前端时间又紧Electron 依然是最稳妥的选择。还要想清楚维护成本Electron 官方版本迭代很快安全更新频繁自动更新、代码签名、构建流水线这几样东西不是上线那天才补的而是从第一天就要排进计划里。我见过不少项目业务代码写完了结果在签名和自动更新上卡了两周就是因为前期没考虑。1.3 进程模型里最容易翻车的内存泄漏聊完选型必须深挖一个所有 Electron 应用迟早会撞上的问题内存泄漏。这里最常见的根源就是全局单例被无限撑大。你在主进程里缓存了所有窗口的引用窗口关了却没清掉时间一长内存就像漏水的桶。实际排查时除了用 Chrome DevTools 的 Memory 面板做堆快照对比我还习惯在主进程定期打印process.memoryUsage()结合app.getAppMetrics()看每个进程的 CPU 和内存变化比凭感觉猜高效得多。另一个出问题的地方是渲染进程里的定时器和全局监听。单页应用切路由时setInterval还在跑事件监听越挂越多窗口一多整个应用就变卡。我的做法是窗口的closed事件里统一做清理页面里养成好习惯所有监听都保存引用不需要时显式移除。简单的规矩能省掉你后面大量排查内存的时间。2. 开发模式里的 electron localhost本地服务联调的关键点2.1 开发服务器正确加载姿势Electron 本地开发基本都会配合 Vite 或 webpack-dev-server这时渲染进程的入口不是打包好的 HTML 文件而是一个本地地址——也就是热词里高频出现的electron localhost。用 Vite 的话典型套路是// 主进程里判断是否开发环境 if (!app.isPackaged) { const devUrl process.env[VITE_DEV_SERVER_URL]; mainWindow.loadURL(devUrl); } else { mainWindow.loadFile(path.join(__dirname, ../dist/index.html)); }这里有个细节VITE_DEV_SERVER_URL是electron-vite或手动启动 Vite 后注入的环境变量千万别自己硬编码http://localhost:5173。因为端口可能被占用Vite 会自动换端口硬编码轻则联调失败重则让你误以为是自己代码写错了。启动顺序也是个高频问题。如果主进程启动太快DevServer 还没就绪loadURL会白屏或报错。稳妥做法是等一下 dev server 就绪再创建窗口或者用 Vite 的server.host和严格端口配置然后把启动脚本串成一个命令比如用concurrently同时拉起 Vite 和 Electron。顺序对了后面热更新才能稳。2.2 跨域、Cookie 与本地联调排查渲染进程的页面是从localhost:5173来的而你的后端 API 在http://localhost:8080。跨域就出现了。浏览器里你习惯了后端配 CORSElectron 里同样要配而且还得注意开发和生产环境的差异。最常见的一个坑开发环境下前端用 fetch 调后端口后端只允许了http://localhost:5173却忽略了请求头里的Origin可能是http://127.0.0.1:5173两个写法稍有不同就报 CORS 错误。先看请求头永远比改代码快。生产环境方案一般是两种一种是把 API 地址也换成https://正式域名从根上避开 CORS另一种是用主进程代理请求——让渲染进程发请求到本地主进程主进程再用 Node 的net模块转发到远端。第二种方式我实际项目里用过很多次既能绕开 CORS又能把 token 和密钥藏在主进程里安全性和稳定性都更好。Cookie 也要单独说。Electron 的 session 默认是独立的跑起来和普通浏览器不共用 Cookie。开发时如果你需要通过 Cookie 联调登录态得在代码里显式设置win.webContents.session.cookies.set({ url: http://localhost:8080, name: session_id, value: token });反之如果发现登录态在 Electron 里始终带不上不要怀疑是后端问题先查 session 分区是不是独立了。2.3 环境变量区分生产与开发很多团队把所有环境变量塞进.env就完事了但在 Electron 里要格外小心。渲染进程里的环境变量打包后是静态嵌入的不要放密钥。真正敏感的东西应该只在主进程读取系统环境变量或配置文件再通过 IPC 按需提供给渲染进程而不是直接编译进 bundle。我建议项目里至少维护三套环境开发development、测试staging、生产production。用app.isPackaged判断是不是 package 后的正式包这是 Electron 官方给的推荐方式比手动判断NODE_ENV要可靠得多。遇到打包后行为跑偏的问题百分之八十都是环境判断的姿势不对。3. electron 菜单那些文档里没写透的细节3.1 Menu 的两种形态应用菜单与上下文菜单Electron 的 Menu 体系分两条线一条是操作系统窗口顶部的应用菜单macOS 的全局菜单栏Windows/Linux 的窗口菜单栏另一条是右键或指定操作弹出来的上下文菜单。很多人不知道的是菜单本身是可以动态更新的菜单里的每一项除了回调click还能渲染checked状态的勾选框甚至嵌一个submenu子菜单。最基础的设置方法是Menu.setApplicationMenu(menu)。这里有个细节在 macOS 上如果不调用这个方法程序仍然会有一个默认菜单包含编辑、窗口、复制、粘贴这些系统角色但在 Windows 和 Linux 上默认菜单通常很简陋几乎等于裸奔所以跨平台开发时菜单必须显式地写出来不要依赖默认值。macOS 的菜单首项永远是应用名比如About、Quit你在模板里写的第一项如果不是 App 名称系统也会自动排列别在这个上面纠结。3.2 菜单模板里最常用的 role 和踩坑记录推荐优先使用role来声明菜单项因为系统内置的role不仅会处理好文案比如 macOS 上的复制是复制Windows 上是Copy还会自动绑定系统快捷键兼容平台原生的行为比如copy、paste、minimize、quit、togglefullscreen。实际项目中我经常在菜单模板里排布的是const template [ { role: fileMenu, label: 文件 }, { role: editMenu, label: 编辑 }, { role: viewMenu, label: 视图 }, { role: windowMenu, label: 窗口 }, { label: 帮助, submenu: [ { label: 官方文档, click: () shell.openExternal(https://www.electronjs.org/) } ] } ]; Menu.setApplicationMenu(Menu.buildFromTemplate(template));有个常见坑如果你在菜单里写死label: 复制且没有绑定role在 macOS 下快捷键可能不生效得手动去配accelerator: CmdOrCtrlC。更糟的是accelerator写法在不同平台还要区分CmdOrCtrl一不留神在 Windows 上条件就错了。所以能用role就绝不要手写 label 和 accelerator省心也不出错。另外注意Menu.buildFromTemplate之后菜单是深拷贝的你后续改原数组不会影响已经构建出的菜单。需要动态改菜单时得重新 build 或者用menu.getMenuItemById方法拿到条目再更新属性别原地改一个已经 build 完的数组那种改了但没反应的体验我深有体会。3.3 托盘菜单与动态菜单实战托盘程序Tray的菜单同样是Menu.buildFromTemplate但有一个细节托盘菜单的点击往往需要动态改变比如显示当前连接状态、显示开关状态。我维护过的一个下载器中托盘菜单里就有一个暂停全部任务的勾选项const contextMenu Menu.buildFromTemplate([ { label: 暂停全部任务, type: checkbox, checked: isPaused, click: (item) { isPaused item.checked; // 再触发主进程里的暂停逻辑 } }, { label: 退出, click: () app.quit() } ]); tray.setContextMenu(contextMenu);这里有个非常容易踩的点点击了菜单项之后如果状态变化需要让菜单重新刷新你不能只改一个全局变量还要再调用一次tray.setContextMenu(Menu.buildFromTemplate(...))重新生成菜单。因为菜单项一旦创建其checked状态就固定了除非你持有 menuItem 引用去手动改。实操下来推荐把生成托盘菜单封装成一个refreshTrayMenu()方法每次状态变更后调用简单粗暴却最可靠。托盘在 Windows 上还有所谓气泡提示和 tooltip在 macOS 上则是setTitle显示状态文字。如果是跨平台托盘不能想当然认为两者表现一致必须在两个系统上各跑一遍看看。 ## 4. electron iap桌面应用内购的正确姿势4.1 想清楚Electron 没有内置 IAP 模块先泼一盆冷水你搜electron-iap大概率什么都搜不到因为 Electron 本身不提供应用内购买的原生 API。所谓electron iap实际是两种方向一种是你的应用上架到 Mac App Store走苹果的 StoreKit 支付另一种是 Windows/Linux 环境下通过第三方支付平台比如 Paddle、FastSpring、Stripe、支付宝/微信等自行实现购买和授权。方向没定下面的代码都无从谈起。很多团队在立项时想得很美我在网页上已经接了微信/支付宝Electron 里复制过来不就行了吗结果发现渲染进程的页面一跑支付跳转、回调、安全校验全被卡住。桌面支付的麻烦在于它没有一个统一的标准而且你需要自己处理订单-支付-校验-发许可这一套完整链路。4.2 主进程封装支付 SDK 的通用流程不管选哪家支付工程架构基本可以收敛成同一套方案。核心原则是支付流程一定走主进程渲染进程只展示界面和结果。原因很简单渲染进程的代码会打包进 asar访问者很容易从资源里翻出各种密钥而主进程代码同样会被打包但因为走的是 Node.js 环境我们可以把密钥放在用户目录的配置文件或环境变量里或者在上架时依赖系统钥匙串破解成本高很多。以第三方支付为例推荐用dialog.showMessageBox配合 shell 打开支付页渲染进程发一个 IPC 事件发起购买主进程拼好支付参数、生成订单号然后shell.openExternal(payUrl)从系统浏览器里打开收银台。用户在浏览器里支付完成后服务器收到回调再通过主进程通知渲染进程刷新授权状态。代码骨架大概长这样// 主进程接收渲染进程发来的购买请求 ipcMain.handle(purchase:start, async (event, sku) { const orderId crypto.randomUUID(); const payUrl await createPaymentLink({ sku, orderId }); await shell.openExternal(payUrl); return { orderId, payUrl }; }); // 服务器回调后主进程轮询或监听通知 ipcMain.handle(license:verify, async () { const result await verifyLicenseFromServer(); return result; });注意支付回调千万不要做成渲染进程里直接起一个定时器去轮询后端而是要配合主进程的setInterval加上心跳阈值超时自动取消订单。实际在发布版本里轮询逻辑放哪个进程都有讲究如果放渲染进程用户一关窗口轮询就停状态就永远对不上。4.3 订阅与恢复购买注意点订阅制逻辑是最容易写乱的部分。我见过一个项目把用户是否订阅直接存在localStorage里结果用户卸载重装订阅直接消失这可不行。规范的做法是三段式本地缓存状态、服务器保存订单、启动时重新校验。启动应用时主进程去服务器拉取最新的订阅到期时间再决定渲染进程给不给人开 VIP这个过程需要加一个 loading 态别让用户看到所有功能都是锁着的再忽然全解开。恢复购买Restore Purchase在 iOS/macOS 生态里是强制要求但很多 Windows 应用不做这个。如果你上了 Mac App StoreStoreKit 的恢复接口必须在 UI 上有入口不然审核大概率被拒。Electron 这边通常是用ipcMain去调用你自己封装的 macOS 原生桥接模块或者干脆走服务器查询订单来实现恢复我建议优先做后者一套代码搞定多平台。做支付最核心的一条经验永远相信服务器状态不要把客户端当成可信来源。用户改系统时间、清缓存、篡改本地存储都可能导致支付状态误判防呆设计要提前做好。4.4 真实场景支付回调延迟和重复订单的坑有一次上线用户在支付宝付款成功后一直没解锁排查发现是支付回调延迟了十几秒而前端轮询三秒一次、五次就放弃直接把用户晾在那里。后来我做了两个改动轮询次数不限但超时时间拉长到两分钟同时在支付结果页放一个我已经支付了的按钮触发人工对账流程把订单号发给客服后台。这种兜底能省很多客诉。另外重复订单也常见。用户在收银台反复点击生成了多笔订单我们要做的不是在支付时疯狂去重而是在服务器端对同一sku同一userId做幂等处理重复生成订单时返回同一个订单号或在前端按钮点击后立即把按钮置灰防止用户连续点击。逻辑简单但很多项目就是漏了这一步。5. electron 打包别再被打包apk带偏了5.1 electron-builder 与 electron-forge 怎么选这个话题经常被人问起尤其是团队里有人看了广告说 Electron 可以发布到手机时我都会先把话说清楚Electron 的目标平台是桌面操作系统打包产物是安装包和便携目录不是安卓 APK、不是 iOS IPA。网上那些声称Electron 打包 apk的方案实际上是在借助 Capacitor / Cordova 之类容器把 Web 前端重新打包成移动端应用和 Electron 本身关系不大了。桌面打包方面市面主流的两个工具是electron-builder和electron-forge。用表格对比一下维度electron-builderelectron-forge维护方社区主导更新活跃Electron 官方团队维护配置复杂度配置文件相对直观,文档多需要配合 plugin,模板更官方多平台构建支持 Win/macOS/Linux可交叉构建部分产物如 Windows 下打 Linux 包支持主流平台但交叉构建限制较多自动更新内置electron-updater配置简单需要额外配置或自己接较繁琐上手速度快默认值合理初期略有门槛极度依赖插件生态我的个人建议如果项目要快速出包、要自动更新选electron-builder它的大多数默认配置够用踩过坑的人也多搜索答案很容易。如果团队高度依赖 Electron 官方发布的新特性选electron-forge跟得更紧但要接受它的一些理念——比如打包流程里好多事情要用官方定的插件去补网上资料相较 builder 略少。5.2 打包配置里的几个关键参数拿electron-builder的electron-builder.yml来说几个关键配置项值得逐字读懂appId: com.company.product productName: 你的应用名 directories: output: dist buildResources: build files: - dist/**/* - node_modules/**/* - package.json asar: true extraResources: - from: resources/ffmpeg to: ffmpeg filter: [**/*] win: target: - target: nsis arch: [x64, arm64] requestedExecutionLevel: asInvoker nsis: oneClick: false allowToChangeInstallationDirectory: true mac: category: public.app-category.productivity target: - target: dmg arch: [x64, arm64] hardenedRuntime: true gatekeeperAssess: falsefiles决定了哪些文件进包这里最容易犯的错是把整个源码目录都带进去连测试文件、开发配置都泄露了。asar会把代码打成一个归档包既加速加载又能一定程度防篡改但如果你把 ffmpeg、可执行文件这些动态资源也塞进asar运行时很可能会出岔子。所以动态资源统一走extraResources放到process.resourcesPath下再用app.isPackaged判断来拼路径这是我被坑过多次后形成的固定套路const resourcePath app.isPackaged ? path.join(process.resourcesPath, ffmpeg) : path.join(__dirname, ../resources/ffmpeg);5.3 为什么桌面应用不能直接产出 APK直接把 Electron 应用打包成 apk在底层上有硬伤Electron 依赖 Node.js 原生绑定和桌面级别的 GUIChromium 渲染进程在线程模型、窗口管理和系统调用上走的是桌面操作系统的路径安卓系统上既没有相同的窗口管理器也没有兼容的原生 ABI 绑定拿一个 Electron build 出来的安装包丢给安卓设备是跑不起来的。如果业务确实要上移动端常见路线有三条。第一把 Electron 里的 Web 前端抽出来用 Capacitor 套壳成安卓/iOS 应用后端接口可以共用但原生能力文件系统、系统托盘等要重新设计或砍掉。第二重新开发一个轻量移动端只做核心功能和数据打通。第三用跨平台框架 Flutter / React Native 整体重写适合对移动端体验要求极高的产品。这三条路线我都会在需求沟通阶段就和客户或产品讲清楚免得后面扯皮。5.4 代码签名与自动更新上线前的生死线代码签名在国内语境下常被忽略但它直接决定你的应用能在多少台电脑上顺利启动。Windows 上没签名的 exeSmartScreen 会拦截用户得更多信息-仍要运行这转化率一崩就是十个点。macOS 上没签名没公证用户从网上下载下来Gatekeeper 会直接杀掉进程连运行机会都不给。签名证书要在打包前就买macOS 公证更是要预留几天时间别掐着发布日才处理。自动更新推荐electron-updater。它支持的 publish provider 包括 GitHub Releases、Generic Server 等只要保证每次新版本包内的latest.yml和安装包文件能被 CDN 访问即可。我踩过的坑是更新下载一半失败后没有回滚或重试机制导致用户卡在更新中后来我把autoDownload设为false先提示用户有更新用户点了再下载下载失败时可以重试体验稳很多。5.5 实际打包过程里最耗时的三个问题打包速度慢是普遍痛点。首次打包要下载 Electron 二进制和各个平台依赖网络慢的话特别煎熬可以在electron-builder.yml里配置镜像源加速。第二个坑是 Windows 的杀毒软件把安装包当病毒删多数是安装目录权限和安装包行为触发误报解决方法是去掉requestedExecutionLevel: requireAdministrator尽量用asInvoker同时代码签名能缓解大部分误报。第三个问题是asar打开后动态 require 模块时报错误module not found这类问题基本是files配置里漏了node_modules深度依赖建议先开启asarUnpack针对问题目录处理不要整包解开。这些坑我在多个项目里轮流踩过一遍越到后面越熟练。如果你们团队准备上一个 Electron 产品我非常建议把上面这几个章节逐条对照、提前验证尤其是主进程和渲染进程的边界、支付和打包这两大块前者决定架构稳不稳后者决定你能不能顺利发版赚钱。