我平时最烦那种“看完文档还是写不出东西”的Electron教程所以我直接把自己常用的配置模板、主进程和渲染进程的通信套路、还有踩过的坑整理成了一份速查手册。这个项目叫“HoRain云--Electron开发速查手册与配置模板”核心就是解决一个问题当你打开Electron官方文档却不知道从哪里开始时有一份能直接抄作业的配置基线。适合刚接触桌面应用的Vue/React前端也适合准备把内部工具搬到桌面的后端同学。先说清楚这份手册解决什么痛点。Electron最大的特点是前后端都跑在Chromium和Node.js之上但这也意味着你有两套进程、两种环境变量、两条通信管道任何一个配置错了轻则功能失效重则直接白屏。网上教程很多但大多是零散知识真到集成蓝牙、配置托盘、打包Vue项目时又得重新翻文档。我把这些零散点整理成可复用的配置模板附上参数说明和坑位预警保证你照着抄一遍能跑通。1. 整体设计思路为什么一份速查手册比视频教程更扛用1.1 速查手册的定位与适用人群Electron开发的知识点非常杂从main进程的窗口管理到renderer进程的页面渲染从IPC通信到系统托盘再到打包分发任何一个环节都可能让人卡半天。视频教程适合入门但真正干活时没人愿意反复拖进度条。速查手册的价值在于“确定性”你遇到问题打开对应章节直接看结论和配置代码不用重新理解上下文。这份手册主要覆盖以下几个维度环境搭建与工程结构不用从零手搓Webpack直接用现成模板并说明为什么这么组织。主进程与渲染进程通信这是Electron的核心难点我会给出三种通信姿势及适用场景。系统能力访问菜单、托盘、蓝牙、剪贴板、文件读写等高频能力。打包与分发配置electron-builder的模板解决跨平台产物问题。工程化经验环境变量、日志、崩溃恢复、自动更新等生产环境要素。1.2 配置模板的设计哲学模板不是把官方文档抄一遍而是把“隐藏的坑”提前填平。比如很多新手喜欢在主进程里直接开一个BrowserWindow然后在webPreferences里设置nodeIntegration: true——第一次跑确实没问题但一旦牵扯到不安全的外部链接访问这种配置就是灾难。所以我的模板默认采用contextIsolation: true、nodeIntegration: false通过preload脚本暴露白名单API。另一个设计思路是“配置可复制”。模板里的代码不是让你读懂原理再去实现而是可以直接粘到项目中改改参数就能用。比如electron-builder的配置模板我会把appId、productName、files、mac、win、linux各平台的target都写清楚你只需要替换自己的应用名和图标。打个比方如果你把Electron官方文档当成字典这份速查手册就是“高频词汇表”加“常用句式”解决“越用越顺手”的问题而不是从头学英语。2. 核心原理与IPC通信主进程、渲染进程、preload的三层协作2.1 进程角色划分与生命周期理解Electron的关键在于明白“两个世界”的边界。主进程main process是Node.js环境负责创建窗口、管理系统事件、调度原生能力渲染进程renderer process是Chromium环境负责渲染HTML/CSS/JS也就是你写的页面。每个标签页就是一个独立的渲染进程这也是为什么Electron不支持多窗口共享一个进程的原因。在这两者之间还有一个容易被忽略的角色preload脚本。它在页面加载前执行拥有有限的Node.js能力因为在隔离环境里同时又可以访问DOM。preload是把主进程能力“安全地”暴露给页面的桥梁。我用的模板大致如下// main.js 关键片段 const { app, BrowserWindow, ipcMain } require(electron); const path require(path); function createWindow() { const win new BrowserWindow({ width: 1200, height: 800, webPreferences: { preload: path.join(__dirname, preload.js), contextIsolation: true, nodeIntegration: false, sandbox: true } }); // 加载本地页面 win.loadFile(./dist/index.html); } app.whenReady().then(() { createWindow(); // macOS 上点击 Dock 图标时重新创建窗口 app.on(activate, () { if (BrowserWindow.getAllWindows().length 0) createWindow(); }); }); app.on(window-all-closed, () { // 非 macOS 平台关闭所有窗口后退出应用 if (process.platform ! darwin) app.quit(); });千万别小看app.on(window-all-closed)这段代码很多人不加判断就在Windows上关窗就退出到了macOS上会变成“应用不退出但Dock图标还在”的尴尬状态。2.2 IPC通信的三种姿势与选择Electron中的IPC进程间通信是高频操作。三种姿势各有适用场景单向发送send/on适合通知类消息比如主进程告诉渲染进程“数据已更新”渲染进程收到后刷新UI不需要返回结果。双向请求invoke/handle适合请求-响应模式比如渲染进程请求读取配置文件主进程返回内容。这是我现在最推荐的方式因为它是Promise原生支持的不会出现回调地狱。同步发送sendSync能不用就不用。它会阻塞主进程如果请求内容比较大界面会卡成PPT。举个例子假设我们要在渲染进程里读取一个本地JSON文件// preload.js const { contextBridge, ipcRenderer } require(electron); contextBridge.exposeInMainWorld(electronAPI, { readConfig: () ipcRenderer.invoke(read-config) });// main.js const fs require(fs); ipcMain.handle(read-config, async (event, filePath) { try { const data await fs.promises.readFile(filePath, utf-8); return { success: true, data: JSON.parse(data) }; } catch (err) { return { success: false, message: err.message }; } });这里有个重要原则所有与Node.js有关的能力都应该在preload层显式暴露不要在渲染进程里直接require(fs)。即使你设置了nodeIntegration: true也强烈不建议因为一旦页面加载了不安全的第三方资源攻击者就能直接操作你的文件系统。这个坑我踩过后面排查篇里细说。2.3 菜单与系统托盘主进程里的UI逻辑Electron的菜单不在DOM里它属于系统级UI必须由主进程操作。很多新手以为菜单就是页面上那几个按钮等到要做右键菜单或顶部菜单栏时直接懵。菜单有两种应用菜单和上下文菜单。// main.js 生成应用菜单 const { Menu, shell } require(electron); const template [ { label: File, submenu: [ { label: Open, accelerator: CmdOrCtrlO, click: () openFile() }, { type: separator }, { role: quit } ] }, { label: Help, submenu: [ { label: Learn More, click: () shell.openExternal(https://www.electronjs.org) } ] } ]; const menu Menu.buildFromTemplate(template); Menu.setApplicationMenu(menu);CmdOrCtrl这个写法很妙它能自动适配macOS的Cmd和Windows/Linux的Ctrl不用你自己判断平台。另外shell.openExternal是打开外部浏览器链接的标准姿势别用win.loadURL去加载外链那样会把外部网页塞进你的应用窗口体验极差。托盘图标也值得注意。有些应用关闭窗口后希望保留在系统托盘这时候需要隐藏主窗口但不退出应用。const { Tray, nativeImage } require(electron); let tray null; app.whenReady().then(() { const icon nativeImage.createFromPath(./assets/trayTemplate.png); tray new Tray(icon); tray.setToolTip(我的应用); tray.setContextMenu(Menu.buildFromTemplate([ { label: 显示主窗口, click: () { mainWindow.show(); } }, { label: 退出, click: () { app.quit(); } } ])); });注意点macOS的菜单栏图标建议用模板图片黑色透明通道Windows则需要彩色图标所以资源目录里别只放一张图。3. 配置模板一个可直接复用的Electron工程骨架3.1 基础目录结构与package.json配置我的模板采用一个很简单的结构适合中小型项目my-electron-app/ ├── src/ │ ├── main/ │ │ └── main.js │ ├── preload/ │ │ └── preload.js │ └── renderer/ │ └── index.html ├── assets/ │ ├── icon.icns │ ├── icon.ico │ └── trayTemplate.png ├── dist/ ├── build/ └── package.jsonpackage.json里关键的配置项{ name: my-electron-app, version: 1.0.0, main: src/main/main.js, scripts: { start: electron ., dev: electron-vite serve, build: electron-vite build }, devDependencies: { electron: ^33.0.0, electron-builder: ^24.13.3, electron-vite: ^2.3.0 }, build: { appId: com.example.myapp, productName: 我的应用, directories: { output: release } } }这里强调一下main字段它告诉Electron从哪里启动主进程路径错误会直接白屏或启动失败。很多新手把main.js放在src目录下却忘了在package.json里改路径结果一直报“找不到模块”。3.2electron-builder打包配置模板打包是Electron开发中最容易踩坑的环节。下面是一份较为完整的electron-builder配置模板包含三平台通用配置appId: com.example.myapp productName: MyApp directories: output: release buildResources: build files: - src/**/* - package.json - node_modules/**/* asar: true win: target: - nsis icon: build/icon.ico nsis: oneClick: false allowToChangeInstallationDirectory: true createDesktopShortcut: true mac: target: - dmg icon: build/icon.icns category: public.app-category.developer-tools linux: target: - AppImage - deb icon: build/icon.png关于asar这个参数很多人犹豫要不要开。我建议开着它会把你的应用代码打包成一个归档文件既能防止别人轻易修改也能减少文件数量加快启动速度。但注意如果代码里用了fs读取项目内部文件路径可能因asar而变得不一样需要配合process.resourcesPath使用。打包时还有一个高频问题图标没生效。Windows上的icon.ico要求必须包含256x256像素的尺寸macOS的icon.icns则包含多尺寸Linux的icon.png建议512x512以上。如果你用自己的图片直接改后缀那大概率会失败。用下electron-icon-builder这类工具自动生成全套图标。3.3 环境变量与多环境构建前后端开发都有环境变量概念但Electron里要分两层看主进程环境变量通过process.env读取可能来自.env文件或系统环境。渲染进程环境变量在开发时通过define或import.meta.env注入生产时以打包时写入的值代替。用electron-vite时我们可以做一个简单的区分// electron.vite.config.js import { defineConfig } from electron-vite; export default defineConfig({ main: { envPrefix: MAIN_VITE_ }, preload: { envPrefix: PRELOAD_VITE_ }, renderer: { envPrefix: VITE_ } });这样在.env文件里写MAIN_VITE_API_URLhttp://localhost:3000主进程代码里就能用process.env.MAIN_VITE_API_URL读取。渲染进程用VITE_API_URL由import.meta.env.VITE_API_URL访问。为什么刻意区分因为Electron主进程和渲染进程的环境变量来源不同混在一起容易出问题主进程里能读到的变量渲染进程不一定能读。如果你在渲染进程里直接process.env生产打包后很可能拿到undefined。3.4 打包Vue项目的完整路径这是搜索热词中出现度很高的话题。Electron Vue项目的打包本质上分两步先把Vue项目构建成静态文件再把这堆文件交给Electron加载。由于Vue默认使用publicPath: /打包后的JS和CSS资源路径是根路径直接loadFile容易白屏。我的模板里会调整Vue的publicPath比如// vite.config.jsVue 项目 export default defineConfig({ base: ./, build: { outDir: dist } });这里base: ./很关键让资源全部走相对路径适配file://协议。否则你从dist/index.html加载时浏览器会尝试请求C:/assets/index.js但实际文件在C:/project/dist/assets/index.js路径不匹配白屏没跑。主进程加载时也加上path处理win.loadFile(path.join(__dirname, ../../dist/index.html));对于Vue Router的history模式默认依赖浏览器路由放Electron里用file://协议访问时createWebHistory()会失效表现为刷新页面就404。解决办法是改成createHashHistory()或者开发时用createWebHistory、生产时切换为hash模式。这个坑几乎每个Vue新手都会遇到别问我怎么知道的。4. 系统能力速查蓝牙、剪切板、文件访问与安全基线4.1 访问蓝牙设备的Electron姿势“Electron访问蓝牙设备”这个搜索热度很高。Electron本身没有独立的蓝牙API主要通过两条路Web Bluetooth API如果Chromium内核支持可以在渲染进程里调用navigator.bluetooth.requestDevice()但Electron默认沙箱环境下支持不完全需要开启特殊flag。Node.js原生模块通过node-gyp编译的模块比如noble在主进程访问蓝牙再通过IPC转发给渲染进程。我的建议是优先走主进程原生模块路线并且封装成IPC接口// main.js 示例 const noble require(noble); ipcMain.handle(bluetooth-scan, async () { noble.on(scanStart, () console.log(扫描开始)); noble.startScanning([], true); // 收集发现的设备并返回 });这条路线的坑在于蓝牙模块依赖高。Windows上可能要安装winusb驱动Linux需要bluetoothctl权限设置macOS则要求应用有NSBluetoothAlwaysUsageDescription描述否则直接崩溃。打包时记得在Info.plist里加上keyNSBluetoothAlwaysUsageDescription/key string应用需要使用蓝牙连接外部设备/string如果只是想控制某个BLE设备还可以用node-ble这类更现代一点的库但都需要在独立线程里跑长连接避免阻塞主进程。4.2 文件读写与剪贴板的高频模式桌面应用最常见的三个能力是文件读取、文件保存、剪贴板操作。文件读写走主进程代码模板如下// main.js ipcMain.handle(save-file, async (event, { fileName, content }) { const { dialog } require(electron); const { writeFile } require(fs/promises); const result await dialog.showSaveDialog({ defaultPath: fileName }); if (!result.canceled) { await writeFile(result.filePath, content, utf-8); return { success: true, path: result.filePath }; } return { success: false, message: 用户取消 }; });剪贴板则更简单// main.js const { clipboard, nativeImage } require(electron); clipboard.writeText(要复制的文本); const text clipboard.readText();值得注意的是Electron的剪贴板API在渲染进程里也能用通过navigator.clipboard但写图片时推荐在主进程用nativeImage因为渲染进程对图片的兼容性处理有限。4.3 安全基线关掉nodeIntegration后的开发习惯我见过太多Electron项目“裸奔”nodeIntegration: true、contextIsolation: false一开就是全家桶。在Electron 5之后官方默认设置开始收紧到Electron 12之后contextIsolation默认为true所以如果你还在老项目里用旧配置建议尽早迁移。安全基线的核心配置webPreferences: { preload: path.join(__dirname, preload.js), contextIsolation: true, nodeIntegration: false, sandbox: true, webSecurity: true }sandbox: true意味着preload脚本里只能使用有限的Node.js API比如ipcRenderer、contextBridge不能require(fs)。如果你需要在preload里读取文件就必须通过IPC请求主进程这种限制是安全的不要试图绕过。同时远程内容加载要警惕。如果你需要在BrowserWindow里打开第三方URL尽量在单独的、无preload的窗口里打开或者直接用shell.openExternal让系统浏览器处理。5. 常见问题与排查技巧实录5.1 IPC通信失效的三大原因IPC通信失效是最常见的“薛定谔式bug”有时候好有时候坏重启一下又好了。绝大多数和下面三个原因有关。第一contextBridge暴露的API名冲突。如果你在preload里定义了一个叫getConfig的API页面里又自己写了一个window.getConfig后者会覆盖前者导致调用失败。排查方法是在渲染进程里console.log(window.electronAPI)看看到底暴露了哪些成员。第二ipcRenderer.on回调绑定在了被更新前的DOM节点上。如果你在Vue组件里用onMounted注册了监听但在组件卸载时没有注销会出现重复监听回调可能执行多次甚至内存泄漏。正确写法import { onMounted, onUnmounted } from vue; function onMessage(_event, payload) { console.log(payload); } onMounted(() { window.electronAPI.onMessage(onMessage); }); onUnmounted(() { window.electronAPI.removeListener(onMessage); });第三主进程监听器在窗口重建后没有重新注册。毕竟主进程并不总是单例的特别是app.on(activate)里再次创建窗口时如果你把ipcMain.handle放在createWindow()函数里相当于每次创建窗口都注册一遍很快报错“listener already exists”。务必把ipcMain.handle放在顶层只注册一次。5.2 打包后白屏或资源路径错乱白屏绝对能排进Electron“心态爆炸榜”前三。常见原因Vue的publicPath未设置./导致静态资源加载不到。解决办法前面说过了改base: ./。主进程loadFile路径错误。开发时用path.join(__dirname, ../dist/index.html)但在生产环境__dirname的指向会变因为代码被包进了app.asar。建议用app.getAppPath()推断项目根目录或直接使用path.join(__dirname, ../../dist/index.html)这样的相对路径。路由模式问题。Vue Router的history模式在file://协议下会挂改成hash模式即可。我之前排查过一个问题开发环境一切正常打包后Windows安装包启动白屏控制台报Not allowed to load local resource: file:///...。最终原因是dist目录打包时被files规则忽略了要在electron-builder的files配置里加上构建产物目录。5.3 应用体积优化与跨平台分发Electron应用体积动辄一两百MB用户下载成本高。优化思路有几条优先使用asar压缩但排除不必要的资源。比如你把整个node_modules打进去里面可能有一堆开发依赖可以在files配置里排除devDependencies相关的模块。对渲染进程产物做代码分割。Electron的渲染进程和浏览器一样可以用动态import()做代码分割把不常用的模块延迟加载。图标、字体、图片压一压。一张几个MB的PNG直接拖垮安装包。推荐用pngquant或imagemin压缩。跨平台分发时要注意三平台的行为差异。Linux下没AppImage或deb的分发习惯Windows下要小心杀毒软件对未签名exe的拦截macOS下Gatekeeper会阻止未经过公证的应用运行。如果预算允许买一份Apple Developer账号做签名和公证能让用户安装体验改善非常多。5.4 常见问题速查表问题现象可能原因排查思路窗口白屏资源路径、路由模式、asar内路径异常打开DevTools查看网络请求失败项先确认HTML加载成功IPC没有返回监听器未注册、事件名不一致、回调未清理在主进程和渲染进程都打日志确认走到哪个环节打包后外部链接打不开用了loadURL而不是shell.openExternal检查代码里是否存在win.loadURL调用托盘图标空白图标格式不符、模板图通道错误macOS用Template ImageWindows用icon.ico蓝牙扫描不到设备驱动、权限描述缺失、BLE过滤器未设置查看系统蓝牙授权状态再用noble写demo验证应用启动慢大模块同步加载、大量require开启Chrome性能面板看主进程卡在哪一步6. 从Electron到国产化适配谈“移植鸿蒙”时的能力映射最近“Electron应用移植鸿蒙”这个关键词搜得很热。很多团队拿到需求第一反应是把代码复制过去但实际做下来会发现这并不叫“移植”更像是“基于新运行时重写”。因为鸿蒙应用生态并不直接兼容Electron的进程模型和Node.js生态。通俗一点讲Electron应用的运行依赖三样东西——Chromium渲染内核、Node.js运行环境、系统原生能力桥接层。鸿蒙的运行时尤其是ArkTS/ArkUI那套使用完全不同的渲染和线程模型不可能直接把BrowserWindow塞进去也不可能让require(fs)直接可用。所以正确的做法是先做“能力映射”把你Electron应用里的每个功能模块对应到目标平台能力的替代方案。比如Electron的主进程fs模块对应鸿蒙的分布式文件服务clipboard对应剪贴板APITray对应卡片或元服务菜单对应系统的菜单接口。这个映射表就是另一份“速查手册”了。有这个思路之后你才能判断哪些功能能低成本改造哪些必须重写。比如纯展示类的工具应用页面重构成本可能远高于预期而主进程逻辑简单、IPC调用少的应用反而能通过WebView方案快速迁移一部分能力。最后再分享一个我自己的使用习惯。我建了一个Git仓库专门放这套模板每次起新项目直接degit拉到本地然后改package.json里的应用名和图标。遇到新问题就顺手写进主文档的“坑位预警”部分两个月之后这份速查手册就成了团队内部真正的知识库。做Electron开发技术深度只是基础更重要的是把重复劳动沉淀成模板。配置文件这种东西写得再漂亮都不如一次真实的启动成功来得踏实。希望这份手册能帮你少走几个弯路多省几个晚上的时间。
Electron开发速查手册：配置模板、IPC通信与打包实战
我平时最烦那种“看完文档还是写不出东西”的Electron教程所以我直接把自己常用的配置模板、主进程和渲染进程的通信套路、还有踩过的坑整理成了一份速查手册。这个项目叫“HoRain云--Electron开发速查手册与配置模板”核心就是解决一个问题当你打开Electron官方文档却不知道从哪里开始时有一份能直接抄作业的配置基线。适合刚接触桌面应用的Vue/React前端也适合准备把内部工具搬到桌面的后端同学。先说清楚这份手册解决什么痛点。Electron最大的特点是前后端都跑在Chromium和Node.js之上但这也意味着你有两套进程、两种环境变量、两条通信管道任何一个配置错了轻则功能失效重则直接白屏。网上教程很多但大多是零散知识真到集成蓝牙、配置托盘、打包Vue项目时又得重新翻文档。我把这些零散点整理成可复用的配置模板附上参数说明和坑位预警保证你照着抄一遍能跑通。1. 整体设计思路为什么一份速查手册比视频教程更扛用1.1 速查手册的定位与适用人群Electron开发的知识点非常杂从main进程的窗口管理到renderer进程的页面渲染从IPC通信到系统托盘再到打包分发任何一个环节都可能让人卡半天。视频教程适合入门但真正干活时没人愿意反复拖进度条。速查手册的价值在于“确定性”你遇到问题打开对应章节直接看结论和配置代码不用重新理解上下文。这份手册主要覆盖以下几个维度环境搭建与工程结构不用从零手搓Webpack直接用现成模板并说明为什么这么组织。主进程与渲染进程通信这是Electron的核心难点我会给出三种通信姿势及适用场景。系统能力访问菜单、托盘、蓝牙、剪贴板、文件读写等高频能力。打包与分发配置electron-builder的模板解决跨平台产物问题。工程化经验环境变量、日志、崩溃恢复、自动更新等生产环境要素。1.2 配置模板的设计哲学模板不是把官方文档抄一遍而是把“隐藏的坑”提前填平。比如很多新手喜欢在主进程里直接开一个BrowserWindow然后在webPreferences里设置nodeIntegration: true——第一次跑确实没问题但一旦牵扯到不安全的外部链接访问这种配置就是灾难。所以我的模板默认采用contextIsolation: true、nodeIntegration: false通过preload脚本暴露白名单API。另一个设计思路是“配置可复制”。模板里的代码不是让你读懂原理再去实现而是可以直接粘到项目中改改参数就能用。比如electron-builder的配置模板我会把appId、productName、files、mac、win、linux各平台的target都写清楚你只需要替换自己的应用名和图标。打个比方如果你把Electron官方文档当成字典这份速查手册就是“高频词汇表”加“常用句式”解决“越用越顺手”的问题而不是从头学英语。2. 核心原理与IPC通信主进程、渲染进程、preload的三层协作2.1 进程角色划分与生命周期理解Electron的关键在于明白“两个世界”的边界。主进程main process是Node.js环境负责创建窗口、管理系统事件、调度原生能力渲染进程renderer process是Chromium环境负责渲染HTML/CSS/JS也就是你写的页面。每个标签页就是一个独立的渲染进程这也是为什么Electron不支持多窗口共享一个进程的原因。在这两者之间还有一个容易被忽略的角色preload脚本。它在页面加载前执行拥有有限的Node.js能力因为在隔离环境里同时又可以访问DOM。preload是把主进程能力“安全地”暴露给页面的桥梁。我用的模板大致如下// main.js 关键片段 const { app, BrowserWindow, ipcMain } require(electron); const path require(path); function createWindow() { const win new BrowserWindow({ width: 1200, height: 800, webPreferences: { preload: path.join(__dirname, preload.js), contextIsolation: true, nodeIntegration: false, sandbox: true } }); // 加载本地页面 win.loadFile(./dist/index.html); } app.whenReady().then(() { createWindow(); // macOS 上点击 Dock 图标时重新创建窗口 app.on(activate, () { if (BrowserWindow.getAllWindows().length 0) createWindow(); }); }); app.on(window-all-closed, () { // 非 macOS 平台关闭所有窗口后退出应用 if (process.platform ! darwin) app.quit(); });千万别小看app.on(window-all-closed)这段代码很多人不加判断就在Windows上关窗就退出到了macOS上会变成“应用不退出但Dock图标还在”的尴尬状态。2.2 IPC通信的三种姿势与选择Electron中的IPC进程间通信是高频操作。三种姿势各有适用场景单向发送send/on适合通知类消息比如主进程告诉渲染进程“数据已更新”渲染进程收到后刷新UI不需要返回结果。双向请求invoke/handle适合请求-响应模式比如渲染进程请求读取配置文件主进程返回内容。这是我现在最推荐的方式因为它是Promise原生支持的不会出现回调地狱。同步发送sendSync能不用就不用。它会阻塞主进程如果请求内容比较大界面会卡成PPT。举个例子假设我们要在渲染进程里读取一个本地JSON文件// preload.js const { contextBridge, ipcRenderer } require(electron); contextBridge.exposeInMainWorld(electronAPI, { readConfig: () ipcRenderer.invoke(read-config) });// main.js const fs require(fs); ipcMain.handle(read-config, async (event, filePath) { try { const data await fs.promises.readFile(filePath, utf-8); return { success: true, data: JSON.parse(data) }; } catch (err) { return { success: false, message: err.message }; } });这里有个重要原则所有与Node.js有关的能力都应该在preload层显式暴露不要在渲染进程里直接require(fs)。即使你设置了nodeIntegration: true也强烈不建议因为一旦页面加载了不安全的第三方资源攻击者就能直接操作你的文件系统。这个坑我踩过后面排查篇里细说。2.3 菜单与系统托盘主进程里的UI逻辑Electron的菜单不在DOM里它属于系统级UI必须由主进程操作。很多新手以为菜单就是页面上那几个按钮等到要做右键菜单或顶部菜单栏时直接懵。菜单有两种应用菜单和上下文菜单。// main.js 生成应用菜单 const { Menu, shell } require(electron); const template [ { label: File, submenu: [ { label: Open, accelerator: CmdOrCtrlO, click: () openFile() }, { type: separator }, { role: quit } ] }, { label: Help, submenu: [ { label: Learn More, click: () shell.openExternal(https://www.electronjs.org) } ] } ]; const menu Menu.buildFromTemplate(template); Menu.setApplicationMenu(menu);CmdOrCtrl这个写法很妙它能自动适配macOS的Cmd和Windows/Linux的Ctrl不用你自己判断平台。另外shell.openExternal是打开外部浏览器链接的标准姿势别用win.loadURL去加载外链那样会把外部网页塞进你的应用窗口体验极差。托盘图标也值得注意。有些应用关闭窗口后希望保留在系统托盘这时候需要隐藏主窗口但不退出应用。const { Tray, nativeImage } require(electron); let tray null; app.whenReady().then(() { const icon nativeImage.createFromPath(./assets/trayTemplate.png); tray new Tray(icon); tray.setToolTip(我的应用); tray.setContextMenu(Menu.buildFromTemplate([ { label: 显示主窗口, click: () { mainWindow.show(); } }, { label: 退出, click: () { app.quit(); } } ])); });注意点macOS的菜单栏图标建议用模板图片黑色透明通道Windows则需要彩色图标所以资源目录里别只放一张图。3. 配置模板一个可直接复用的Electron工程骨架3.1 基础目录结构与package.json配置我的模板采用一个很简单的结构适合中小型项目my-electron-app/ ├── src/ │ ├── main/ │ │ └── main.js │ ├── preload/ │ │ └── preload.js │ └── renderer/ │ └── index.html ├── assets/ │ ├── icon.icns │ ├── icon.ico │ └── trayTemplate.png ├── dist/ ├── build/ └── package.jsonpackage.json里关键的配置项{ name: my-electron-app, version: 1.0.0, main: src/main/main.js, scripts: { start: electron ., dev: electron-vite serve, build: electron-vite build }, devDependencies: { electron: ^33.0.0, electron-builder: ^24.13.3, electron-vite: ^2.3.0 }, build: { appId: com.example.myapp, productName: 我的应用, directories: { output: release } } }这里强调一下main字段它告诉Electron从哪里启动主进程路径错误会直接白屏或启动失败。很多新手把main.js放在src目录下却忘了在package.json里改路径结果一直报“找不到模块”。3.2electron-builder打包配置模板打包是Electron开发中最容易踩坑的环节。下面是一份较为完整的electron-builder配置模板包含三平台通用配置appId: com.example.myapp productName: MyApp directories: output: release buildResources: build files: - src/**/* - package.json - node_modules/**/* asar: true win: target: - nsis icon: build/icon.ico nsis: oneClick: false allowToChangeInstallationDirectory: true createDesktopShortcut: true mac: target: - dmg icon: build/icon.icns category: public.app-category.developer-tools linux: target: - AppImage - deb icon: build/icon.png关于asar这个参数很多人犹豫要不要开。我建议开着它会把你的应用代码打包成一个归档文件既能防止别人轻易修改也能减少文件数量加快启动速度。但注意如果代码里用了fs读取项目内部文件路径可能因asar而变得不一样需要配合process.resourcesPath使用。打包时还有一个高频问题图标没生效。Windows上的icon.ico要求必须包含256x256像素的尺寸macOS的icon.icns则包含多尺寸Linux的icon.png建议512x512以上。如果你用自己的图片直接改后缀那大概率会失败。用下electron-icon-builder这类工具自动生成全套图标。3.3 环境变量与多环境构建前后端开发都有环境变量概念但Electron里要分两层看主进程环境变量通过process.env读取可能来自.env文件或系统环境。渲染进程环境变量在开发时通过define或import.meta.env注入生产时以打包时写入的值代替。用electron-vite时我们可以做一个简单的区分// electron.vite.config.js import { defineConfig } from electron-vite; export default defineConfig({ main: { envPrefix: MAIN_VITE_ }, preload: { envPrefix: PRELOAD_VITE_ }, renderer: { envPrefix: VITE_ } });这样在.env文件里写MAIN_VITE_API_URLhttp://localhost:3000主进程代码里就能用process.env.MAIN_VITE_API_URL读取。渲染进程用VITE_API_URL由import.meta.env.VITE_API_URL访问。为什么刻意区分因为Electron主进程和渲染进程的环境变量来源不同混在一起容易出问题主进程里能读到的变量渲染进程不一定能读。如果你在渲染进程里直接process.env生产打包后很可能拿到undefined。3.4 打包Vue项目的完整路径这是搜索热词中出现度很高的话题。Electron Vue项目的打包本质上分两步先把Vue项目构建成静态文件再把这堆文件交给Electron加载。由于Vue默认使用publicPath: /打包后的JS和CSS资源路径是根路径直接loadFile容易白屏。我的模板里会调整Vue的publicPath比如// vite.config.jsVue 项目 export default defineConfig({ base: ./, build: { outDir: dist } });这里base: ./很关键让资源全部走相对路径适配file://协议。否则你从dist/index.html加载时浏览器会尝试请求C:/assets/index.js但实际文件在C:/project/dist/assets/index.js路径不匹配白屏没跑。主进程加载时也加上path处理win.loadFile(path.join(__dirname, ../../dist/index.html));对于Vue Router的history模式默认依赖浏览器路由放Electron里用file://协议访问时createWebHistory()会失效表现为刷新页面就404。解决办法是改成createHashHistory()或者开发时用createWebHistory、生产时切换为hash模式。这个坑几乎每个Vue新手都会遇到别问我怎么知道的。4. 系统能力速查蓝牙、剪切板、文件访问与安全基线4.1 访问蓝牙设备的Electron姿势“Electron访问蓝牙设备”这个搜索热度很高。Electron本身没有独立的蓝牙API主要通过两条路Web Bluetooth API如果Chromium内核支持可以在渲染进程里调用navigator.bluetooth.requestDevice()但Electron默认沙箱环境下支持不完全需要开启特殊flag。Node.js原生模块通过node-gyp编译的模块比如noble在主进程访问蓝牙再通过IPC转发给渲染进程。我的建议是优先走主进程原生模块路线并且封装成IPC接口// main.js 示例 const noble require(noble); ipcMain.handle(bluetooth-scan, async () { noble.on(scanStart, () console.log(扫描开始)); noble.startScanning([], true); // 收集发现的设备并返回 });这条路线的坑在于蓝牙模块依赖高。Windows上可能要安装winusb驱动Linux需要bluetoothctl权限设置macOS则要求应用有NSBluetoothAlwaysUsageDescription描述否则直接崩溃。打包时记得在Info.plist里加上keyNSBluetoothAlwaysUsageDescription/key string应用需要使用蓝牙连接外部设备/string如果只是想控制某个BLE设备还可以用node-ble这类更现代一点的库但都需要在独立线程里跑长连接避免阻塞主进程。4.2 文件读写与剪贴板的高频模式桌面应用最常见的三个能力是文件读取、文件保存、剪贴板操作。文件读写走主进程代码模板如下// main.js ipcMain.handle(save-file, async (event, { fileName, content }) { const { dialog } require(electron); const { writeFile } require(fs/promises); const result await dialog.showSaveDialog({ defaultPath: fileName }); if (!result.canceled) { await writeFile(result.filePath, content, utf-8); return { success: true, path: result.filePath }; } return { success: false, message: 用户取消 }; });剪贴板则更简单// main.js const { clipboard, nativeImage } require(electron); clipboard.writeText(要复制的文本); const text clipboard.readText();值得注意的是Electron的剪贴板API在渲染进程里也能用通过navigator.clipboard但写图片时推荐在主进程用nativeImage因为渲染进程对图片的兼容性处理有限。4.3 安全基线关掉nodeIntegration后的开发习惯我见过太多Electron项目“裸奔”nodeIntegration: true、contextIsolation: false一开就是全家桶。在Electron 5之后官方默认设置开始收紧到Electron 12之后contextIsolation默认为true所以如果你还在老项目里用旧配置建议尽早迁移。安全基线的核心配置webPreferences: { preload: path.join(__dirname, preload.js), contextIsolation: true, nodeIntegration: false, sandbox: true, webSecurity: true }sandbox: true意味着preload脚本里只能使用有限的Node.js API比如ipcRenderer、contextBridge不能require(fs)。如果你需要在preload里读取文件就必须通过IPC请求主进程这种限制是安全的不要试图绕过。同时远程内容加载要警惕。如果你需要在BrowserWindow里打开第三方URL尽量在单独的、无preload的窗口里打开或者直接用shell.openExternal让系统浏览器处理。5. 常见问题与排查技巧实录5.1 IPC通信失效的三大原因IPC通信失效是最常见的“薛定谔式bug”有时候好有时候坏重启一下又好了。绝大多数和下面三个原因有关。第一contextBridge暴露的API名冲突。如果你在preload里定义了一个叫getConfig的API页面里又自己写了一个window.getConfig后者会覆盖前者导致调用失败。排查方法是在渲染进程里console.log(window.electronAPI)看看到底暴露了哪些成员。第二ipcRenderer.on回调绑定在了被更新前的DOM节点上。如果你在Vue组件里用onMounted注册了监听但在组件卸载时没有注销会出现重复监听回调可能执行多次甚至内存泄漏。正确写法import { onMounted, onUnmounted } from vue; function onMessage(_event, payload) { console.log(payload); } onMounted(() { window.electronAPI.onMessage(onMessage); }); onUnmounted(() { window.electronAPI.removeListener(onMessage); });第三主进程监听器在窗口重建后没有重新注册。毕竟主进程并不总是单例的特别是app.on(activate)里再次创建窗口时如果你把ipcMain.handle放在createWindow()函数里相当于每次创建窗口都注册一遍很快报错“listener already exists”。务必把ipcMain.handle放在顶层只注册一次。5.2 打包后白屏或资源路径错乱白屏绝对能排进Electron“心态爆炸榜”前三。常见原因Vue的publicPath未设置./导致静态资源加载不到。解决办法前面说过了改base: ./。主进程loadFile路径错误。开发时用path.join(__dirname, ../dist/index.html)但在生产环境__dirname的指向会变因为代码被包进了app.asar。建议用app.getAppPath()推断项目根目录或直接使用path.join(__dirname, ../../dist/index.html)这样的相对路径。路由模式问题。Vue Router的history模式在file://协议下会挂改成hash模式即可。我之前排查过一个问题开发环境一切正常打包后Windows安装包启动白屏控制台报Not allowed to load local resource: file:///...。最终原因是dist目录打包时被files规则忽略了要在electron-builder的files配置里加上构建产物目录。5.3 应用体积优化与跨平台分发Electron应用体积动辄一两百MB用户下载成本高。优化思路有几条优先使用asar压缩但排除不必要的资源。比如你把整个node_modules打进去里面可能有一堆开发依赖可以在files配置里排除devDependencies相关的模块。对渲染进程产物做代码分割。Electron的渲染进程和浏览器一样可以用动态import()做代码分割把不常用的模块延迟加载。图标、字体、图片压一压。一张几个MB的PNG直接拖垮安装包。推荐用pngquant或imagemin压缩。跨平台分发时要注意三平台的行为差异。Linux下没AppImage或deb的分发习惯Windows下要小心杀毒软件对未签名exe的拦截macOS下Gatekeeper会阻止未经过公证的应用运行。如果预算允许买一份Apple Developer账号做签名和公证能让用户安装体验改善非常多。5.4 常见问题速查表问题现象可能原因排查思路窗口白屏资源路径、路由模式、asar内路径异常打开DevTools查看网络请求失败项先确认HTML加载成功IPC没有返回监听器未注册、事件名不一致、回调未清理在主进程和渲染进程都打日志确认走到哪个环节打包后外部链接打不开用了loadURL而不是shell.openExternal检查代码里是否存在win.loadURL调用托盘图标空白图标格式不符、模板图通道错误macOS用Template ImageWindows用icon.ico蓝牙扫描不到设备驱动、权限描述缺失、BLE过滤器未设置查看系统蓝牙授权状态再用noble写demo验证应用启动慢大模块同步加载、大量require开启Chrome性能面板看主进程卡在哪一步6. 从Electron到国产化适配谈“移植鸿蒙”时的能力映射最近“Electron应用移植鸿蒙”这个关键词搜得很热。很多团队拿到需求第一反应是把代码复制过去但实际做下来会发现这并不叫“移植”更像是“基于新运行时重写”。因为鸿蒙应用生态并不直接兼容Electron的进程模型和Node.js生态。通俗一点讲Electron应用的运行依赖三样东西——Chromium渲染内核、Node.js运行环境、系统原生能力桥接层。鸿蒙的运行时尤其是ArkTS/ArkUI那套使用完全不同的渲染和线程模型不可能直接把BrowserWindow塞进去也不可能让require(fs)直接可用。所以正确的做法是先做“能力映射”把你Electron应用里的每个功能模块对应到目标平台能力的替代方案。比如Electron的主进程fs模块对应鸿蒙的分布式文件服务clipboard对应剪贴板APITray对应卡片或元服务菜单对应系统的菜单接口。这个映射表就是另一份“速查手册”了。有这个思路之后你才能判断哪些功能能低成本改造哪些必须重写。比如纯展示类的工具应用页面重构成本可能远高于预期而主进程逻辑简单、IPC调用少的应用反而能通过WebView方案快速迁移一部分能力。最后再分享一个我自己的使用习惯。我建了一个Git仓库专门放这套模板每次起新项目直接degit拉到本地然后改package.json里的应用名和图标。遇到新问题就顺手写进主文档的“坑位预警”部分两个月之后这份速查手册就成了团队内部真正的知识库。做Electron开发技术深度只是基础更重要的是把重复劳动沉淀成模板。配置文件这种东西写得再漂亮都不如一次真实的启动成功来得踏实。希望这份手册能帮你少走几个弯路多省几个晚上的时间。
