1. 为什么是Electron一个桌面开发者的视角如果你是一个前端开发者或者对Web技术栈比较熟悉最近又恰好被老板或产品经理提了一个需求“我们需要一个桌面客户端要能跨Windows、macOS和Linux界面要好看开发要快。” 那么你大概率会和我几年前一样开始在各种技术方案里打转。从原生的C/C#/Objective-C到Java Swing再到Qt、WPF最后目光总会落到Electron上。它太有名了也太有争议了。有人说它“吃内存”、“打包体积大”但另一边VS Code、Slack、Figma、Discord这些我们每天都在用的生产力工具又都是它的“金字招牌”。今天我就从一个实际用Electron做过几个商业化项目的老兵角度来聊聊怎么快速上手以及那些官方文档里不会写的“实战心得”。简单说Electron让你能用HTML、CSS和JavaScript来构建跨平台的桌面应用。它的核心架构很清晰一个主进程Main Process负责管理应用生命周期、原生窗口和系统交互多个渲染进程Renderer Process就是一个个Chromium浏览器窗口负责跑你的前端页面。两者通过IPC进程间通信来“对话”。这个模式对于前端开发者来说几乎是零门槛切入桌面开发的最大福音。你不用再去学一套全新的UI绘制和事件处理机制你熟悉的React、Vue、Svelte或者哪怕是最朴素的jQuery都能直接搬过来用。2. 环境准备从零到一的第一个窗口很多人觉得环境搭建就是npm install但对于Electron新手第一个坑往往就在这里。我们一步步来把可能遇到的问题都提前规避掉。2.1 Node.js与包管理器的选择首先你需要一个Node.js环境。我强烈建议使用Node.js的LTS长期支持版本比如当前的18.x或20.x。Electron对Node版本有一定要求太老或太新的非LTS版本可能会遇到奇怪的兼容性问题。你可以通过node -v和npm -v来检查。关于包管理器npm是随Node自带的完全够用。如果你习惯用yarn或pnpm也完全没问题但需要注意Electron的一些工具链比如electron-builder在非npm环境下可能会有细微的配置差异。为了减少不必要的麻烦在第一个项目里我建议先用npm。2.2 初始化项目与安装Electron找一个空文件夹我们开始初始化项目mkdir my-first-electron-app cd my-first-electron-app npm init -y这会生成一个package.json文件。接下来安装Electron。这里有个关键点不要把Electron安装到全局-g。因为不同项目可能需要不同版本的Electron全局安装会导致版本冲突。我们把它作为开发依赖devDependency安装到本地。npm install electron --save-dev这个过程可能会比较慢因为Electron的包包含了完整的Chromium和Node.js运行时体积不小。如果遇到网络问题可以考虑配置镜像源。安装完成后你的package.json里会多出一行devDependencies: { electron: ^29.0.0 // 版本号可能不同 }2.3 创建最简应用骨架一个最基础的Electron应用需要三个文件package.json- 我们已经有了需要修改一下。main.js- 主进程入口文件。index.html- 渲染进程要加载的第一个页面。首先修改package.json指定主进程入口并添加一个启动脚本{ name: my-first-electron-app, version: 1.0.0, description: , main: main.js, // 指定主进程入口文件 scripts: { start: electron ., // 添加启动脚本 test: echo \Error: no test specified\ exit 1 }, devDependencies: { electron: ^29.0.0 } }接着创建main.js。这是应用的大脑负责创建窗口和处理系统事件。// main.js const { app, BrowserWindow } require(electron); const path require(path); // 保持对窗口对象的全局引用如果不这么做当JavaScript对象被垃圾回收时窗口将会自动关闭。 let mainWindow; function createWindow() { // 创建浏览器窗口 mainWindow new BrowserWindow({ width: 800, height: 600, webPreferences: { nodeIntegration: true, // 是否集成Node.js contextIsolation: false, // 是否启用上下文隔离安全性相关后续详谈 } }); // 并且加载应用的 index.html // 这里有两种方式 // 1. 加载本地文件 mainWindow.loadFile(index.html); // 2. 加载远程URL比如你的开发服务器 // mainWindow.loadURL(http://localhost:3000); // 打开开发者工具开发环境用 mainWindow.webContents.openDevTools(); // 当窗口被关闭时触发 mainWindow.on(closed, function () { // 取消引用窗口对象如果你的应用支持多窗口通常会将窗口存储在数组中这里删除对应的元素。 mainWindow null; }); } // Electron 会在初始化后准备创建浏览器窗口时调用这个函数。 app.whenReady().then(createWindow); // 当所有窗口都被关闭后退出应用 app.on(window-all-closed, function () { // 在 macOS 上除非用户用 Cmd Q 确定地退出否则应用及其菜单栏会保持激活。 if (process.platform ! darwin) app.quit(); }); app.on(activate, function () { // 在 macOS 上当点击 dock 图标并且没有其他窗口打开时通常在应用中重新创建一个窗口。 if (mainWindow null) createWindow(); });然后创建一个简单的index.html!DOCTYPE html html head meta charsetUTF-8 titleHello Electron!/title /head body h1Hello from Electron!/h1 pWe are using Node.js span idnode-version/span, Chromium span idchrome-version/span, and Electron span idelectron-version/span./p script // 这里可以写前端逻辑因为上面设置了 nodeIntegration: true所以可以直接使用Node.js模块 document.getElementById(node-version).innerText process.versions.node; document.getElementById(chrome-version).innerText process.versions.chrome; document.getElementById(electron-version).innerText process.versions.electron; /script /body /html现在在终端运行npm start你应该能看到一个桌面窗口弹出来并显示Node.js、Chromium和Electron的版本信息。恭喜你的第一个Electron应用跑起来了注意上面main.js中webPreferences的nodeIntegration: true和contextIsolation: false是一个不安全的配置它允许渲染进程直接访问完整的Node.js API。这虽然方便但会带来严重的安全风险如果加载了不可信的远程内容。这里只是为了快速演示在正式项目中我们绝不能这样配置。安全策略是Electron开发的重中之重我们会在后面专门讨论。3. 理解核心主进程、渲染进程与IPC通信跑通“Hello World”只是第一步理解Electron的进程模型是写出健壮应用的关键。很多初学者遇到的“这个API怎么在页面里调用不了”、“为什么这里报错说require未定义”等问题都源于对进程模型的混淆。3.1 主进程应用的管家主进程是应用的入口点运行在Node.js环境中。它通过app模块控制应用的生命周期启动、退出通过BrowserWindow模块创建和管理应用窗口。每个Electron应用有且只有一个主进程。主进程的职责包括创建和管理所有窗口new BrowserWindow(...)。处理系统事件如应用激活activate、所有窗口关闭window-all-closed、程序坞图标点击macOS等。访问完整的Node.js API可以读写文件、调用系统命令、连接数据库等。定义应用菜单Menu、托盘图标Tray、全局快捷键GlobalShortcut等。你可以把主进程想象成公司的后台管理员它不直接面对用户不显示UI但负责所有的资源调度和后勤保障。3.2 渲染进程展示给用户的窗口每一个由BrowserWindow创建的窗口都运行着一个独立的渲染进程。渲染进程本质上是一个Chromium浏览器标签页负责加载和显示HTML/CSS/JS处理用户交互。一个应用可以有多个渲染进程多个窗口。默认情况下渲染进程的行为和普通网页一样出于安全考虑它不能直接访问Node.js API。它的职责是渲染用户界面。执行前端JavaScript逻辑。通过DOM与用户交互。渲染进程就像公司的前台或销售直接与客户用户打交道展示产品界面但权限受到限制。3.3 IPC进程间的通信桥梁既然主进程和渲染进程各司其职那它们如何协作呢比如渲染进程里的一个按钮点击后需要让主进程去读写一个本地文件然后再把结果返回给页面显示。这就需要进程间通信IPC。Electron提供了ipcMain主进程端和ipcRenderer渲染进程端模块来实现这个功能。这是一种基于事件的异步通信模型。一个典型的IPC流程示例从渲染进程向主进程发送请求并获取回复首先在主进程main.js中监听来自渲染进程的频道channel消息并执行操作如读取文件后回复// main.js (部分代码) const { app, BrowserWindow, ipcMain } require(electron); // 引入ipcMain const fs require(fs).promises; const path require(path); // ... 其他代码createWindow等 ... // 监听渲染进程通过‘read-file’频道发来的请求 ipcMain.handle(read-file, async (event, filePath) { try { // 主进程可以安全地使用Node.js的fs模块 const data await fs.readFile(path.resolve(__dirname, filePath), utf-8); return { success: true, data }; // 返回结果给渲染进程 } catch (error) { return { success: false, error: error.message }; } });然后在渲染进程的页面脚本比如renderer.js中发送请求并处理回复!-- index.html 部分 -- button idreadBtn读取配置文件/button p idcontent/p script const { ipcRenderer } require(electron); // 注意这需要nodeIntegration为true不安全 document.getElementById(readBtn).addEventListener(click, async () { // 向主进程的‘read-file’频道发送请求并等待Promise结果 const result await ipcRenderer.invoke(read-file, config.json); if (result.success) { document.getElementById(content).innerText result.data; } else { console.error(读取失败:, result.error); } }); /script上面渲染进程的写法直接使用了require(‘electron’)这依赖于我们之前设置的不安全的nodeIntegration: true。在生产环境中这是绝对不允许的。那么安全的通信方式是什么呢这就引出了“预加载脚本Preload Script”和“上下文隔离Context Isolation”。4. 安全第一预加载脚本与上下文隔离安全是Electron开发中最容易被忽视也最致命的一环。如果你的应用会加载任何外部或用户提供的内容不安全的设计将导致攻击者可以轻易执行任意系统命令。Electron官方文档将安全放在非常突出的位置我们必须严格遵守。4.1 为什么默认配置不安全我们之前为了图方便在创建窗口时设置了webPreferences: { nodeIntegration: true, contextIsolation: false, }nodeIntegration: true允许渲染进程直接使用require()等Node.js API。contextIsolation: false关闭了上下文隔离。这意味着渲染进程的JavaScript运行环境你的前端代码和Electron的内部运行环境在同一个全局上下文中。这两者结合意味着如果恶意代码被注入到你的渲染进程例如通过一个XSS漏洞或加载了一个被篡改的第三方脚本它就可以直接调用require(‘child_process’)来执行系统命令或者用require(‘fs’)任意读写用户磁盘文件后果不堪设想。4.2 安全的最佳实践启用上下文隔离与预加载脚本正确的做法是永远保持nodeIntegration: false。渲染进程不应该直接访问Node。永远保持contextIsolation: trueElectron 12 之后默认就是true。这会将你的前端代码与Electron内部代码、预加载脚本代码隔离在不同的JavaScript上下文类似不同的V8虚拟机实例中防止原型链污染等攻击。使用预加载脚本Preload Script来作为渲染进程安全地访问主进程能力的唯一桥梁。预加载脚本是一个特殊的脚本它在渲染进程的网页开始加载之前在拥有Node.js访问权限的上下文中运行但与渲染进程的主上下文你的前端代码是隔离的。我们可以在这里通过contextBridge上下文桥向渲染进程暴露有限的、安全的API。让我们重构上面的文件读取例子采用安全模式第一步创建预加载脚本preload.js// preload.js const { contextBridge, ipcRenderer } require(electron); // 通过 contextBridge向渲染进程的 window 对象上安全地注入一个自定义 API。 contextBridge.exposeInMainWorld( electronAPI, // 注入对象的命名空间比如 window.electronAPI { readFile: (filePath) ipcRenderer.invoke(read-file, filePath), // 可以在这里暴露更多安全的API例如 // onUpdateCounter: (callback) ipcRenderer.on(update-counter, callback), // setTitle: (title) ipcRenderer.send(set-title, title), } );这个脚本运行在“预加载上下文”中它可以访问ipcRenderer和require。但它通过contextBridge.exposeInMainWorld只将readFile这个函数暴露给了渲染进程的window.electronAPI。渲染进程无法直接拿到ipcRenderer或任何Node模块。第二步修改主进程main.js加载预加载脚本并启用安全设置// main.js (修改createWindow部分) function createWindow() { mainWindow new BrowserWindow({ width: 800, height: 600, webPreferences: { preload: path.join(__dirname, preload.js), // 指定预加载脚本路径 nodeIntegration: false, // 必须为 false contextIsolation: true, // 必须为 true (默认值) } }); // ... 其他代码不变 ... } // ... IPC监听器保持不变 ...第三步修改渲染进程的HTML/JS使用暴露的API!-- index.html -- button idreadBtn安全地读取配置文件/button p idcontent/p script // 现在我们不能直接 require(electron) 了因为 nodeIntegration 是 false。 // 但是我们可以使用预加载脚本暴露出来的 window.electronAPI document.getElementById(readBtn).addEventListener(click, async () { // 调用预加载脚本暴露的 API const result await window.electronAPI.readFile(config.json); if (result.success) { document.getElementById(content).innerText result.data; } else { console.error(读取失败:, result.error); } }); /script这样一来渲染进程中的代码哪怕是恶意注入的代码只能通过我们预先定义好的window.electronAPI.readFile来请求读取文件而无法执行任何其他危险操作。攻击面被极大地缩小了。实操心得在项目一开始就搭建好这个安全框架。不要为了“快速验证”而使用不安全配置否则后期重构成本极高。将nodeIntegration和contextIsolation的设置固化在你的项目模板或脚手架里。5. 打包与分发从开发到交付用户开发调试完成后你需要将应用打包成可执行文件如.exe, .dmg, .AppImage等分发给用户。这是另一个容易踩坑的环节。5.1 打包工具选型electron-builder vs. electron-forge主流打包工具有两个electron-builder和electron-forge。electron-forge更“全栈”集成了模板创建、开发、测试、打包、发布的全流程开箱即用适合新手快速上手。electron-builder功能极其强大和灵活配置项多支持自动更新、各种目标格式NSIS、AppX、dmg、deb/rpm等、代码签名、公证Notarization等高级功能是复杂生产项目的首选。根据我的经验如果你要做严肃的商业化发布直接选择electron-builder。它的社区更活跃遇到问题更容易找到解决方案对Windows代码签名和macOS公证流程的支持也更成熟。5.2 使用electron-builder进行基础打包首先安装它npm install electron-builder --save-dev然后在package.json中添加基本的配置段{ name: my-first-electron-app, version: 1.0.0, description: 我的第一个Electron应用, main: main.js, scripts: { start: electron ., pack: electron-builder --dir, // 生成未打包的目录用于测试 dist: electron-builder // 生成安装包 }, devDependencies: { electron: ^29.0.0, electron-builder: ^24.0.0 }, build: { appId: com.yourcompany.yourapp, productName: MyFirstElectronApp, directories: { output: dist // 输出目录 }, files: [ main.js, preload.js, index.html, package.json // 明确列出需要打包的文件和文件夹如“assets/”, “node_modules/”等 // 使用“**/*”需谨慎避免把.git、测试文件等打进去 ], mac: { category: public.app-category.developer-tools }, win: { target: nsis }, linux: { target: AppImage } } }关键配置解析appId: 应用的唯一标识符遵循反向域名规则如com.github.electron。productName: 最终生成的应用名称。files:这是最重要的配置之一指定哪些文件需要被打包进应用的asar归档中。默认会包含除了node_modulesdevDependencies会被排除之外的所有文件。但最好显式列出避免把源码映射source map、测试用例等无关文件打包进去增大体积。mac/win/linux: 各平台特定的配置比如mac的应用分类、Windows的安装包类型NSIS是最常见的、Linux的包格式AppImage, snap, deb等。运行npm run distelectron-builder会根据当前操作系统在dist文件夹下生成对应的安装包。第一次运行会下载很多依赖如Windows的NSIS工具链需要耐心等待。5.3 优化打包体积与性能生成的安装包动辄上百MB这是Electron常被诟病的一点。我们可以通过一些手段优化依赖管理仔细检查package.json中的dependencies和devDependencies。只有应用运行时必需的包如某个UI库、数据库驱动才应该放在dependencies里。构建工具、代码检查工具等一定要放在devDependencies。electron-builder默认会排除devDependencies。使用asar归档electron-builder默认会将应用代码打包成asar格式这是一种类似tar的归档格式能保护源码一定程度、加快require速度并减少文件数量。保持启用即可。资源文件优化图片、字体等资源文件使用合适的格式和压缩率。可以考虑在构建流程中加入图片压缩步骤。代码分割与懒加载如果你的前端部分使用了Webpack等打包工具可以利用代码分割Code Splitting和动态导入Dynamic Import将非首屏必需的代码拆分开减少初始加载体积。考虑使用更小的运行时对于极致的体积要求可以研究electron-vite基于Vite的构建工具对Tree-shaking更友好或electron/rebuild配合系统原生模块的重建。踩坑实录曾经有一个项目打包后体积异常大。排查后发现是因为在files配置中使用了“**/*”导致将整个.git目录和node_modules/.cache里面有很多缓存二进制文件都打了进去。所以务必显式、精确地配置files字段。6. 开发体验优化调试、热重载与自动化用原始的方式npm start开发每次修改代码都要手动重启应用效率很低。我们需要搭建一个高效的开发环境。6.1 主进程与渲染进程的调试渲染进程调试最简单在创建窗口时调用mainWindow.webContents.openDevTools()即可打开Chrome开发者工具。你可以像调试普通网页一样调试CSS、JavaScript、网络请求等。主进程调试相对复杂。推荐使用VSCode。在项目根目录创建.vscode/launch.json{ version: 0.2.0, configurations: [ { name: Debug Main Process, type: node, request: launch, cwd: ${workspaceFolder}, runtimeExecutable: ${workspaceFolder}/node_modules/.bin/electron, windows: { runtimeExecutable: ${workspaceFolder}/node_modules/.bin/electron.cmd }, args: [.], outputCapture: std } ] }然后在VSCode中打上断点按F5启动调试就可以像调试Node.js程序一样调试主进程了。6.2 实现热重载Hot Reload修改代码后自动刷新应用能极大提升效率。需要区分主进程和渲染进程的热重载。渲染进程热重载如果你的前端部分使用了Vite、Webpack Dev Server等它们本身就支持HMR热模块替换。你只需要让Electron窗口加载开发服务器的URL如http://localhost:3000而不是本地文件loadFile(‘index.html’)。这样前端代码的改动就能实时生效。主进程热重载主进程是Node.js进程实现完全的热重载比较困难因为涉及原生模块和状态管理。但我们可以实现“自动重启”。使用nodemon或electron-reloader等工具。以electron-reloader为例npm install electron-reloader --save-dev在main.js的顶部添加// main.js (开发环境) try { require(electron-reloader)(module, { debug: true, watchRenderer: false // 如果你用了前端开发服务器这里设为false }); } catch (_) { console.log(electron-reloader failed); } // ... 其他代码 ...这样当你修改并保存main.js或preload.js时Electron应用会自动重启。注意这可能会丢失应用状态比如窗口位置但对于开发阶段来说效率提升是显著的。6.3 集成现代前端框架绝大多数Electron应用的前端部分都会使用React、Vue、Svelte等框架。集成它们并不复杂。以Vite React为例使用Vite官方模板创建前端项目npm create vitelatest renderer -- --template react将生成的renderer文件夹放在Electron项目根目录下。修改Electron的main.js在开发环境下加载Vite开发服务器地址// main.js (createWindow函数内) if (process.env.NODE_ENV development) { mainWindow.loadURL(http://localhost:5173); // Vite默认端口 mainWindow.webContents.openDevTools(); } else { mainWindow.loadFile(path.join(__dirname, ./dist-renderer/index.html)); // 生产环境加载打包后的文件 }修改package.json的脚本同时启动Vite开发服务器和Electron。可以使用concurrently或npm-run-all工具或者写一个简单的Node.js脚本启动两者。配置electron-builder的files字段将前端构建产物如dist-renderer包含进去。这样你就拥有了一个前端支持热更新HMR、主进程支持自动重启的现代化Electron开发环境。7. 进阶之路原生能力、性能与更新掌握了基础和安全之后你可以探索Electron更强大的能力让应用变得更专业。7.1 调用系统原生能力Electron通过主进程模块提供了丰富的原生API这是Web应用无法做到的系统对话框dialog模块可以打开文件选择框、保存对话框、消息提示框等。菜单Menu和MenuItem模块用于创建应用菜单顶部菜单栏和上下文菜单右键菜单。托盘图标Tray模块可以在系统托盘Windows或菜单栏macOS创建常驻图标。全局快捷键globalShortcut模块可以注册全局键盘快捷键即使应用没有焦点也能响应。电源监视powerMonitor可以监听系统挂起、唤醒、锁屏等事件。剪切板clipboard进行复杂的剪切板读写。原生主题nativeTheme可以检测和响应系统的深色/浅色模式切换。使用这些API的通用模式是在预加载脚本中暴露一个安全的接口渲染进程调用这个接口通过IPC通知主进程主进程再调用对应的原生模块完成操作。7.2 性能监控与优化尽管现代硬件性能强大但作为开发者仍需关注性能。内存泄漏排查Electron应用常见的内存泄漏点在于事件监听器未移除、DOM节点未清理、以及IPC监听器未清理。可以使用Chrome开发者工具的Memory面板拍摄堆快照Heap Snapshot进行对比分析。特别注意ipcRenderer.on和window.addEventListener在组件卸载或页面关闭时需要移除。GPU加速确保webPreferences中的hardwareAcceleration选项为true默认值以利用GPU进行页面渲染。后台页面节流对于隐藏的或非激活的BrowserWindow可以启用backgroundThrottling默认启用使页面在后台时降低JavaScript定时器的执行频率。禁用非必要功能如果应用不需要Node.js集成比如一个纯粹的展示窗口创建窗口时设置nodeIntegration: false和contextIsolation: true。如果不需要远程模块设置enableRemoteModule: falseElectron 14后已移除该模块。这些都能减少潜在的开销和攻击面。7.3 应用自动更新对于桌面应用提供平滑的自动更新体验至关重要。electron-builder配合一些云服务如GitHub Releases、Amazon S3、私有服务器可以轻松实现。核心流程是打包发布时electron-builder会生成一个latest.yml或latest-mac.yml等文件里面包含了新版本的信息和文件哈希。应用启动时或定期主进程使用autoUpdater模块在macOS上常用electron-updater它跨平台支持更好检查这个yml文件。如果发现新版本下载安装包通常是.exe或.dmg的增量或全量包。下载完成后提示用户重启应用以完成安装。electron-builder的publish配置可以自动化上传构建产物和更新元数据到各种平台。集成自动更新是让应用走向成熟的关键一步务必在项目中期就规划并实施。从创建一个简单的窗口到理解进程模型与安全架构再到打包分发和搭建高效开发环境最后触及原生能力与性能优化这条路径覆盖了Electron入门到进阶的核心环节。每个环节都有其细节和“坑”但一旦走通你就会发现用Web技术构建功能强大、体验优秀的桌面应用并非难事。关键在于从一开始就建立起正确的安全观念和项目结构这能让你在后续的开发中避开无数麻烦。剩下的就是结合具体的业务需求去探索Electron那浩瀚的API世界了。 Electron桌面应用开发实战：从零构建跨平台客户端
1. 为什么是Electron一个桌面开发者的视角如果你是一个前端开发者或者对Web技术栈比较熟悉最近又恰好被老板或产品经理提了一个需求“我们需要一个桌面客户端要能跨Windows、macOS和Linux界面要好看开发要快。” 那么你大概率会和我几年前一样开始在各种技术方案里打转。从原生的C/C#/Objective-C到Java Swing再到Qt、WPF最后目光总会落到Electron上。它太有名了也太有争议了。有人说它“吃内存”、“打包体积大”但另一边VS Code、Slack、Figma、Discord这些我们每天都在用的生产力工具又都是它的“金字招牌”。今天我就从一个实际用Electron做过几个商业化项目的老兵角度来聊聊怎么快速上手以及那些官方文档里不会写的“实战心得”。简单说Electron让你能用HTML、CSS和JavaScript来构建跨平台的桌面应用。它的核心架构很清晰一个主进程Main Process负责管理应用生命周期、原生窗口和系统交互多个渲染进程Renderer Process就是一个个Chromium浏览器窗口负责跑你的前端页面。两者通过IPC进程间通信来“对话”。这个模式对于前端开发者来说几乎是零门槛切入桌面开发的最大福音。你不用再去学一套全新的UI绘制和事件处理机制你熟悉的React、Vue、Svelte或者哪怕是最朴素的jQuery都能直接搬过来用。2. 环境准备从零到一的第一个窗口很多人觉得环境搭建就是npm install但对于Electron新手第一个坑往往就在这里。我们一步步来把可能遇到的问题都提前规避掉。2.1 Node.js与包管理器的选择首先你需要一个Node.js环境。我强烈建议使用Node.js的LTS长期支持版本比如当前的18.x或20.x。Electron对Node版本有一定要求太老或太新的非LTS版本可能会遇到奇怪的兼容性问题。你可以通过node -v和npm -v来检查。关于包管理器npm是随Node自带的完全够用。如果你习惯用yarn或pnpm也完全没问题但需要注意Electron的一些工具链比如electron-builder在非npm环境下可能会有细微的配置差异。为了减少不必要的麻烦在第一个项目里我建议先用npm。2.2 初始化项目与安装Electron找一个空文件夹我们开始初始化项目mkdir my-first-electron-app cd my-first-electron-app npm init -y这会生成一个package.json文件。接下来安装Electron。这里有个关键点不要把Electron安装到全局-g。因为不同项目可能需要不同版本的Electron全局安装会导致版本冲突。我们把它作为开发依赖devDependency安装到本地。npm install electron --save-dev这个过程可能会比较慢因为Electron的包包含了完整的Chromium和Node.js运行时体积不小。如果遇到网络问题可以考虑配置镜像源。安装完成后你的package.json里会多出一行devDependencies: { electron: ^29.0.0 // 版本号可能不同 }2.3 创建最简应用骨架一个最基础的Electron应用需要三个文件package.json- 我们已经有了需要修改一下。main.js- 主进程入口文件。index.html- 渲染进程要加载的第一个页面。首先修改package.json指定主进程入口并添加一个启动脚本{ name: my-first-electron-app, version: 1.0.0, description: , main: main.js, // 指定主进程入口文件 scripts: { start: electron ., // 添加启动脚本 test: echo \Error: no test specified\ exit 1 }, devDependencies: { electron: ^29.0.0 } }接着创建main.js。这是应用的大脑负责创建窗口和处理系统事件。// main.js const { app, BrowserWindow } require(electron); const path require(path); // 保持对窗口对象的全局引用如果不这么做当JavaScript对象被垃圾回收时窗口将会自动关闭。 let mainWindow; function createWindow() { // 创建浏览器窗口 mainWindow new BrowserWindow({ width: 800, height: 600, webPreferences: { nodeIntegration: true, // 是否集成Node.js contextIsolation: false, // 是否启用上下文隔离安全性相关后续详谈 } }); // 并且加载应用的 index.html // 这里有两种方式 // 1. 加载本地文件 mainWindow.loadFile(index.html); // 2. 加载远程URL比如你的开发服务器 // mainWindow.loadURL(http://localhost:3000); // 打开开发者工具开发环境用 mainWindow.webContents.openDevTools(); // 当窗口被关闭时触发 mainWindow.on(closed, function () { // 取消引用窗口对象如果你的应用支持多窗口通常会将窗口存储在数组中这里删除对应的元素。 mainWindow null; }); } // Electron 会在初始化后准备创建浏览器窗口时调用这个函数。 app.whenReady().then(createWindow); // 当所有窗口都被关闭后退出应用 app.on(window-all-closed, function () { // 在 macOS 上除非用户用 Cmd Q 确定地退出否则应用及其菜单栏会保持激活。 if (process.platform ! darwin) app.quit(); }); app.on(activate, function () { // 在 macOS 上当点击 dock 图标并且没有其他窗口打开时通常在应用中重新创建一个窗口。 if (mainWindow null) createWindow(); });然后创建一个简单的index.html!DOCTYPE html html head meta charsetUTF-8 titleHello Electron!/title /head body h1Hello from Electron!/h1 pWe are using Node.js span idnode-version/span, Chromium span idchrome-version/span, and Electron span idelectron-version/span./p script // 这里可以写前端逻辑因为上面设置了 nodeIntegration: true所以可以直接使用Node.js模块 document.getElementById(node-version).innerText process.versions.node; document.getElementById(chrome-version).innerText process.versions.chrome; document.getElementById(electron-version).innerText process.versions.electron; /script /body /html现在在终端运行npm start你应该能看到一个桌面窗口弹出来并显示Node.js、Chromium和Electron的版本信息。恭喜你的第一个Electron应用跑起来了注意上面main.js中webPreferences的nodeIntegration: true和contextIsolation: false是一个不安全的配置它允许渲染进程直接访问完整的Node.js API。这虽然方便但会带来严重的安全风险如果加载了不可信的远程内容。这里只是为了快速演示在正式项目中我们绝不能这样配置。安全策略是Electron开发的重中之重我们会在后面专门讨论。3. 理解核心主进程、渲染进程与IPC通信跑通“Hello World”只是第一步理解Electron的进程模型是写出健壮应用的关键。很多初学者遇到的“这个API怎么在页面里调用不了”、“为什么这里报错说require未定义”等问题都源于对进程模型的混淆。3.1 主进程应用的管家主进程是应用的入口点运行在Node.js环境中。它通过app模块控制应用的生命周期启动、退出通过BrowserWindow模块创建和管理应用窗口。每个Electron应用有且只有一个主进程。主进程的职责包括创建和管理所有窗口new BrowserWindow(...)。处理系统事件如应用激活activate、所有窗口关闭window-all-closed、程序坞图标点击macOS等。访问完整的Node.js API可以读写文件、调用系统命令、连接数据库等。定义应用菜单Menu、托盘图标Tray、全局快捷键GlobalShortcut等。你可以把主进程想象成公司的后台管理员它不直接面对用户不显示UI但负责所有的资源调度和后勤保障。3.2 渲染进程展示给用户的窗口每一个由BrowserWindow创建的窗口都运行着一个独立的渲染进程。渲染进程本质上是一个Chromium浏览器标签页负责加载和显示HTML/CSS/JS处理用户交互。一个应用可以有多个渲染进程多个窗口。默认情况下渲染进程的行为和普通网页一样出于安全考虑它不能直接访问Node.js API。它的职责是渲染用户界面。执行前端JavaScript逻辑。通过DOM与用户交互。渲染进程就像公司的前台或销售直接与客户用户打交道展示产品界面但权限受到限制。3.3 IPC进程间的通信桥梁既然主进程和渲染进程各司其职那它们如何协作呢比如渲染进程里的一个按钮点击后需要让主进程去读写一个本地文件然后再把结果返回给页面显示。这就需要进程间通信IPC。Electron提供了ipcMain主进程端和ipcRenderer渲染进程端模块来实现这个功能。这是一种基于事件的异步通信模型。一个典型的IPC流程示例从渲染进程向主进程发送请求并获取回复首先在主进程main.js中监听来自渲染进程的频道channel消息并执行操作如读取文件后回复// main.js (部分代码) const { app, BrowserWindow, ipcMain } require(electron); // 引入ipcMain const fs require(fs).promises; const path require(path); // ... 其他代码createWindow等 ... // 监听渲染进程通过‘read-file’频道发来的请求 ipcMain.handle(read-file, async (event, filePath) { try { // 主进程可以安全地使用Node.js的fs模块 const data await fs.readFile(path.resolve(__dirname, filePath), utf-8); return { success: true, data }; // 返回结果给渲染进程 } catch (error) { return { success: false, error: error.message }; } });然后在渲染进程的页面脚本比如renderer.js中发送请求并处理回复!-- index.html 部分 -- button idreadBtn读取配置文件/button p idcontent/p script const { ipcRenderer } require(electron); // 注意这需要nodeIntegration为true不安全 document.getElementById(readBtn).addEventListener(click, async () { // 向主进程的‘read-file’频道发送请求并等待Promise结果 const result await ipcRenderer.invoke(read-file, config.json); if (result.success) { document.getElementById(content).innerText result.data; } else { console.error(读取失败:, result.error); } }); /script上面渲染进程的写法直接使用了require(‘electron’)这依赖于我们之前设置的不安全的nodeIntegration: true。在生产环境中这是绝对不允许的。那么安全的通信方式是什么呢这就引出了“预加载脚本Preload Script”和“上下文隔离Context Isolation”。4. 安全第一预加载脚本与上下文隔离安全是Electron开发中最容易被忽视也最致命的一环。如果你的应用会加载任何外部或用户提供的内容不安全的设计将导致攻击者可以轻易执行任意系统命令。Electron官方文档将安全放在非常突出的位置我们必须严格遵守。4.1 为什么默认配置不安全我们之前为了图方便在创建窗口时设置了webPreferences: { nodeIntegration: true, contextIsolation: false, }nodeIntegration: true允许渲染进程直接使用require()等Node.js API。contextIsolation: false关闭了上下文隔离。这意味着渲染进程的JavaScript运行环境你的前端代码和Electron的内部运行环境在同一个全局上下文中。这两者结合意味着如果恶意代码被注入到你的渲染进程例如通过一个XSS漏洞或加载了一个被篡改的第三方脚本它就可以直接调用require(‘child_process’)来执行系统命令或者用require(‘fs’)任意读写用户磁盘文件后果不堪设想。4.2 安全的最佳实践启用上下文隔离与预加载脚本正确的做法是永远保持nodeIntegration: false。渲染进程不应该直接访问Node。永远保持contextIsolation: trueElectron 12 之后默认就是true。这会将你的前端代码与Electron内部代码、预加载脚本代码隔离在不同的JavaScript上下文类似不同的V8虚拟机实例中防止原型链污染等攻击。使用预加载脚本Preload Script来作为渲染进程安全地访问主进程能力的唯一桥梁。预加载脚本是一个特殊的脚本它在渲染进程的网页开始加载之前在拥有Node.js访问权限的上下文中运行但与渲染进程的主上下文你的前端代码是隔离的。我们可以在这里通过contextBridge上下文桥向渲染进程暴露有限的、安全的API。让我们重构上面的文件读取例子采用安全模式第一步创建预加载脚本preload.js// preload.js const { contextBridge, ipcRenderer } require(electron); // 通过 contextBridge向渲染进程的 window 对象上安全地注入一个自定义 API。 contextBridge.exposeInMainWorld( electronAPI, // 注入对象的命名空间比如 window.electronAPI { readFile: (filePath) ipcRenderer.invoke(read-file, filePath), // 可以在这里暴露更多安全的API例如 // onUpdateCounter: (callback) ipcRenderer.on(update-counter, callback), // setTitle: (title) ipcRenderer.send(set-title, title), } );这个脚本运行在“预加载上下文”中它可以访问ipcRenderer和require。但它通过contextBridge.exposeInMainWorld只将readFile这个函数暴露给了渲染进程的window.electronAPI。渲染进程无法直接拿到ipcRenderer或任何Node模块。第二步修改主进程main.js加载预加载脚本并启用安全设置// main.js (修改createWindow部分) function createWindow() { mainWindow new BrowserWindow({ width: 800, height: 600, webPreferences: { preload: path.join(__dirname, preload.js), // 指定预加载脚本路径 nodeIntegration: false, // 必须为 false contextIsolation: true, // 必须为 true (默认值) } }); // ... 其他代码不变 ... } // ... IPC监听器保持不变 ...第三步修改渲染进程的HTML/JS使用暴露的API!-- index.html -- button idreadBtn安全地读取配置文件/button p idcontent/p script // 现在我们不能直接 require(electron) 了因为 nodeIntegration 是 false。 // 但是我们可以使用预加载脚本暴露出来的 window.electronAPI document.getElementById(readBtn).addEventListener(click, async () { // 调用预加载脚本暴露的 API const result await window.electronAPI.readFile(config.json); if (result.success) { document.getElementById(content).innerText result.data; } else { console.error(读取失败:, result.error); } }); /script这样一来渲染进程中的代码哪怕是恶意注入的代码只能通过我们预先定义好的window.electronAPI.readFile来请求读取文件而无法执行任何其他危险操作。攻击面被极大地缩小了。实操心得在项目一开始就搭建好这个安全框架。不要为了“快速验证”而使用不安全配置否则后期重构成本极高。将nodeIntegration和contextIsolation的设置固化在你的项目模板或脚手架里。5. 打包与分发从开发到交付用户开发调试完成后你需要将应用打包成可执行文件如.exe, .dmg, .AppImage等分发给用户。这是另一个容易踩坑的环节。5.1 打包工具选型electron-builder vs. electron-forge主流打包工具有两个electron-builder和electron-forge。electron-forge更“全栈”集成了模板创建、开发、测试、打包、发布的全流程开箱即用适合新手快速上手。electron-builder功能极其强大和灵活配置项多支持自动更新、各种目标格式NSIS、AppX、dmg、deb/rpm等、代码签名、公证Notarization等高级功能是复杂生产项目的首选。根据我的经验如果你要做严肃的商业化发布直接选择electron-builder。它的社区更活跃遇到问题更容易找到解决方案对Windows代码签名和macOS公证流程的支持也更成熟。5.2 使用electron-builder进行基础打包首先安装它npm install electron-builder --save-dev然后在package.json中添加基本的配置段{ name: my-first-electron-app, version: 1.0.0, description: 我的第一个Electron应用, main: main.js, scripts: { start: electron ., pack: electron-builder --dir, // 生成未打包的目录用于测试 dist: electron-builder // 生成安装包 }, devDependencies: { electron: ^29.0.0, electron-builder: ^24.0.0 }, build: { appId: com.yourcompany.yourapp, productName: MyFirstElectronApp, directories: { output: dist // 输出目录 }, files: [ main.js, preload.js, index.html, package.json // 明确列出需要打包的文件和文件夹如“assets/”, “node_modules/”等 // 使用“**/*”需谨慎避免把.git、测试文件等打进去 ], mac: { category: public.app-category.developer-tools }, win: { target: nsis }, linux: { target: AppImage } } }关键配置解析appId: 应用的唯一标识符遵循反向域名规则如com.github.electron。productName: 最终生成的应用名称。files:这是最重要的配置之一指定哪些文件需要被打包进应用的asar归档中。默认会包含除了node_modulesdevDependencies会被排除之外的所有文件。但最好显式列出避免把源码映射source map、测试用例等无关文件打包进去增大体积。mac/win/linux: 各平台特定的配置比如mac的应用分类、Windows的安装包类型NSIS是最常见的、Linux的包格式AppImage, snap, deb等。运行npm run distelectron-builder会根据当前操作系统在dist文件夹下生成对应的安装包。第一次运行会下载很多依赖如Windows的NSIS工具链需要耐心等待。5.3 优化打包体积与性能生成的安装包动辄上百MB这是Electron常被诟病的一点。我们可以通过一些手段优化依赖管理仔细检查package.json中的dependencies和devDependencies。只有应用运行时必需的包如某个UI库、数据库驱动才应该放在dependencies里。构建工具、代码检查工具等一定要放在devDependencies。electron-builder默认会排除devDependencies。使用asar归档electron-builder默认会将应用代码打包成asar格式这是一种类似tar的归档格式能保护源码一定程度、加快require速度并减少文件数量。保持启用即可。资源文件优化图片、字体等资源文件使用合适的格式和压缩率。可以考虑在构建流程中加入图片压缩步骤。代码分割与懒加载如果你的前端部分使用了Webpack等打包工具可以利用代码分割Code Splitting和动态导入Dynamic Import将非首屏必需的代码拆分开减少初始加载体积。考虑使用更小的运行时对于极致的体积要求可以研究electron-vite基于Vite的构建工具对Tree-shaking更友好或electron/rebuild配合系统原生模块的重建。踩坑实录曾经有一个项目打包后体积异常大。排查后发现是因为在files配置中使用了“**/*”导致将整个.git目录和node_modules/.cache里面有很多缓存二进制文件都打了进去。所以务必显式、精确地配置files字段。6. 开发体验优化调试、热重载与自动化用原始的方式npm start开发每次修改代码都要手动重启应用效率很低。我们需要搭建一个高效的开发环境。6.1 主进程与渲染进程的调试渲染进程调试最简单在创建窗口时调用mainWindow.webContents.openDevTools()即可打开Chrome开发者工具。你可以像调试普通网页一样调试CSS、JavaScript、网络请求等。主进程调试相对复杂。推荐使用VSCode。在项目根目录创建.vscode/launch.json{ version: 0.2.0, configurations: [ { name: Debug Main Process, type: node, request: launch, cwd: ${workspaceFolder}, runtimeExecutable: ${workspaceFolder}/node_modules/.bin/electron, windows: { runtimeExecutable: ${workspaceFolder}/node_modules/.bin/electron.cmd }, args: [.], outputCapture: std } ] }然后在VSCode中打上断点按F5启动调试就可以像调试Node.js程序一样调试主进程了。6.2 实现热重载Hot Reload修改代码后自动刷新应用能极大提升效率。需要区分主进程和渲染进程的热重载。渲染进程热重载如果你的前端部分使用了Vite、Webpack Dev Server等它们本身就支持HMR热模块替换。你只需要让Electron窗口加载开发服务器的URL如http://localhost:3000而不是本地文件loadFile(‘index.html’)。这样前端代码的改动就能实时生效。主进程热重载主进程是Node.js进程实现完全的热重载比较困难因为涉及原生模块和状态管理。但我们可以实现“自动重启”。使用nodemon或electron-reloader等工具。以electron-reloader为例npm install electron-reloader --save-dev在main.js的顶部添加// main.js (开发环境) try { require(electron-reloader)(module, { debug: true, watchRenderer: false // 如果你用了前端开发服务器这里设为false }); } catch (_) { console.log(electron-reloader failed); } // ... 其他代码 ...这样当你修改并保存main.js或preload.js时Electron应用会自动重启。注意这可能会丢失应用状态比如窗口位置但对于开发阶段来说效率提升是显著的。6.3 集成现代前端框架绝大多数Electron应用的前端部分都会使用React、Vue、Svelte等框架。集成它们并不复杂。以Vite React为例使用Vite官方模板创建前端项目npm create vitelatest renderer -- --template react将生成的renderer文件夹放在Electron项目根目录下。修改Electron的main.js在开发环境下加载Vite开发服务器地址// main.js (createWindow函数内) if (process.env.NODE_ENV development) { mainWindow.loadURL(http://localhost:5173); // Vite默认端口 mainWindow.webContents.openDevTools(); } else { mainWindow.loadFile(path.join(__dirname, ./dist-renderer/index.html)); // 生产环境加载打包后的文件 }修改package.json的脚本同时启动Vite开发服务器和Electron。可以使用concurrently或npm-run-all工具或者写一个简单的Node.js脚本启动两者。配置electron-builder的files字段将前端构建产物如dist-renderer包含进去。这样你就拥有了一个前端支持热更新HMR、主进程支持自动重启的现代化Electron开发环境。7. 进阶之路原生能力、性能与更新掌握了基础和安全之后你可以探索Electron更强大的能力让应用变得更专业。7.1 调用系统原生能力Electron通过主进程模块提供了丰富的原生API这是Web应用无法做到的系统对话框dialog模块可以打开文件选择框、保存对话框、消息提示框等。菜单Menu和MenuItem模块用于创建应用菜单顶部菜单栏和上下文菜单右键菜单。托盘图标Tray模块可以在系统托盘Windows或菜单栏macOS创建常驻图标。全局快捷键globalShortcut模块可以注册全局键盘快捷键即使应用没有焦点也能响应。电源监视powerMonitor可以监听系统挂起、唤醒、锁屏等事件。剪切板clipboard进行复杂的剪切板读写。原生主题nativeTheme可以检测和响应系统的深色/浅色模式切换。使用这些API的通用模式是在预加载脚本中暴露一个安全的接口渲染进程调用这个接口通过IPC通知主进程主进程再调用对应的原生模块完成操作。7.2 性能监控与优化尽管现代硬件性能强大但作为开发者仍需关注性能。内存泄漏排查Electron应用常见的内存泄漏点在于事件监听器未移除、DOM节点未清理、以及IPC监听器未清理。可以使用Chrome开发者工具的Memory面板拍摄堆快照Heap Snapshot进行对比分析。特别注意ipcRenderer.on和window.addEventListener在组件卸载或页面关闭时需要移除。GPU加速确保webPreferences中的hardwareAcceleration选项为true默认值以利用GPU进行页面渲染。后台页面节流对于隐藏的或非激活的BrowserWindow可以启用backgroundThrottling默认启用使页面在后台时降低JavaScript定时器的执行频率。禁用非必要功能如果应用不需要Node.js集成比如一个纯粹的展示窗口创建窗口时设置nodeIntegration: false和contextIsolation: true。如果不需要远程模块设置enableRemoteModule: falseElectron 14后已移除该模块。这些都能减少潜在的开销和攻击面。7.3 应用自动更新对于桌面应用提供平滑的自动更新体验至关重要。electron-builder配合一些云服务如GitHub Releases、Amazon S3、私有服务器可以轻松实现。核心流程是打包发布时electron-builder会生成一个latest.yml或latest-mac.yml等文件里面包含了新版本的信息和文件哈希。应用启动时或定期主进程使用autoUpdater模块在macOS上常用electron-updater它跨平台支持更好检查这个yml文件。如果发现新版本下载安装包通常是.exe或.dmg的增量或全量包。下载完成后提示用户重启应用以完成安装。electron-builder的publish配置可以自动化上传构建产物和更新元数据到各种平台。集成自动更新是让应用走向成熟的关键一步务必在项目中期就规划并实施。从创建一个简单的窗口到理解进程模型与安全架构再到打包分发和搭建高效开发环境最后触及原生能力与性能优化这条路径覆盖了Electron入门到进阶的核心环节。每个环节都有其细节和“坑”但一旦走通你就会发现用Web技术构建功能强大、体验优秀的桌面应用并非难事。关键在于从一开始就建立起正确的安全观念和项目结构这能让你在后续的开发中避开无数麻烦。剩下的就是结合具体的业务需求去探索Electron那浩瀚的API世界了。