最近团队里接了个活儿要把一套内部管理系统从浏览器搬到桌面技术选型时几乎没怎么犹豫就定了 Electron。理由很简单前端团队不需要额外学 C 或 C#现有 React 代码能直接复用跨平台的需求也能一次满足。不过真正上手之后才发现Electron 的入门门槛确实不高但离“用好”还有一段距离——尤其是屏幕缩放、菜单定制、打包路径这些问题几乎每个项目都会踩一遍。这篇教程我就按自己实际走过的流程来写从环境准备到进程模型再到几个高频坑位的排查思路希望能帮你省掉一些我当初消耗在搜索和试错上的时间。1. 为什么用 Electron它解决了什么问题你又该为它付出什么1.1 Electron 的本质Electron 说白了就是把 Chromium 浏览器内核和 Node.js 运行时打包装进同一个可执行文件。你的界面用 HTML/CSS/JavaScript 去写底层能力通过 Node.js 去调比如读写本地文件、访问系统剪贴板、操作窗口这些在纯浏览器里做不了的事情在 Electron 里都能做。这个设计带来了一个很直观的好处Web 技术栈的开发者可以无缝切换到桌面应用开发。我在项目中用到的 React、Vue 甚至原生 DOM 操作全都照常工作。而且因为 Chromium 内核是被打包进应用里的你不需要担心用户机器上装的是 Chrome 还是 Edge界面表现完全由你控制。代价也很明显包体积大、内存占用高。一个最简单的 Electron 应用安装包动辄 80MB 起步运行时内存占用轻松超过 200MB这在今天还算能接受但如果你的目标用户用的是老旧办公电脑就得认真掂量掂量。还有一点容易被忽略Electron 自带了一个 Chromium所以你需要定期跟进升级版本来修补浏览器内核的安全漏洞这属于长期维护成本。1.2 适合与不适合的场景从我实际接过的项目来看Electron 最适合这几类场景企业内部工具用户量不大但需要跨平台且界面重交互。已经有一套 Web 应用想快速包装出桌面客户端打通本地文件系统能力。团队以 Web 前端为主希望在短期内交付桌面端产品。不太适合的场景则包括对安装包体积有严格要求的消费者级软件、需要极低内存占用的后台常驻工具、对系统级性能和稳定性要求极高的专业软件。我做选型时有个习惯先问“这个软件是否能容忍一个浏览器内核常驻运行”。如果答案是否那就不要选 Electron直接考虑 Tauri 或原生开发会更稳妥。这不是说 Electron 不行而是要清楚每项技术都有它的边界。2. 从零到一环境准备与最小可运行应用2.1 初始化项目我假设你已经装好了 Node.js版本建议 18 以上。Electron 本身只是一个 npm 包所以第一步很简单mkdir my-electron-app cd my-electron-app npm init -y npm install --save-dev electronnpm init -y会生成一个默认的 package.json。安装 electron 的时候要注意国内网络环境下载二进制文件可能会失败所以我会提前设置镜像环境变量# macOS / Linux export ELECTRON_MIRRORhttps://npmmirror.com/mirrors/electron/ # Windows PowerShell $env:ELECTRON_MIRRORhttps://npmmirror.com/mirrors/electron/设置完之后再执行npm install --save-dev electron速度会明显提升。安装完成后务必要跑一下版本验证npx electron --version如果这里能正常输出版本号说明 Electron 的二进制文件已经正确下载并解压后面基本不会出什么大问题如果这一步报错多办是网络或缓存问题清掉 npm 缓存再重装即可。2.2 主进程、页面与 package.json 三件套一个最简 Electron 应用需要三个文件主进程入口、页面文件、配置文件。这是每一个 Electron 项目的骨架我先把它们都列出来再逐一解释。// main.js const { app, BrowserWindow } require(electron) function createWindow() { const win new BrowserWindow({ width: 1024, height: 768, webPreferences: { nodeIntegration: false, contextIsolation: true, preload: path.join(__dirname, preload.js) } }) win.loadFile(index.html) } app.whenReady().then(() { createWindow() app.on(activate, () { if (BrowserWindow.getAllWindows().length 0) { createWindow() } }) }) app.on(window-all-closed, () { if (process.platform ! darwin) { app.quit() } })!-- index.html -- !DOCTYPE html html head meta charsetUTF-8 / title我的第一个 Electron 应用/title /head body h1Hello from Electron/h1 /body /html// package.json { name: my-electron-app, version: 1.0.0, main: main.js, scripts: { start: electron . }, devDependencies: { electron: ^31.0.0 } }需要注意package.json里必须有main字段指向主进程入口文件否则 Electron 不知道从哪里启动。一切就绪后运行npm start看到窗口弹出、页面显示Hello from Electron你的第一个 Electron 应用就跑通了。这段代码里createWindow里的webPreferences配置我建议从第一行代码开始就保持contextIsolation: true不要把nodeIntegration打开。这个习惯能帮你少踩很多安全方面的坑后面我会专门展开讲。3. 主进程与渲染进程Electron 的神经系统3.1 进程模型与 IPC 通信Electron 应用在运行时至少有两个进程主进程和渲染进程。主进程对应的是main.js由 Node.js 运行时驱动。它负责创建窗口、管理应用生命周期、调用系统能力是整个应用的控制中心。渲染进程对应的是窗口里加载的页面它其实就是一个 Chromium tab页面里的 JavaScript 只能运行在“浏览器环境”里不能直接调用 Node.js API。这里有个新手最容易搞混的点在页面里写require(fs)在默认的安全配置下会直接报错。这不是 Electron 出了问题而是设计上就是如此。如果业务确实需要读取本地文件正确的姿势是让渲染进程通过 IPC 向主进程发请求由主进程去操作文件系统再把结果回传。一条标准的 IPC 链路是这样的// preload.js const { contextBridge, ipcRenderer } require(electron) contextBridge.exposeInMainWorld(electronAPI, { readFile: (filePath) ipcRenderer.invoke(file:read, filePath) })// main.js 中增加 const { ipcMain } require(electron) const fs require(fs/promises) ipcMain.handle(file:read, async (event, filePath) { try { const content await fs.readFile(filePath, utf-8) return { success: true, content } } catch (error) { return { success: false, message: error.message } } })页面里就可以这么调用window.electronAPI.readFile(/path/to/file.txt) .then((result) { if (result.success) { console.log(result.content) } })contextBridge.exposeInMainWorld的作用是把指定的 API 注入到渲染进程的全局对象window上页面代码通过这个对象与主进程通信既不直接暴露 Node.js 能力又能实现业务所需的功能。我经历过不少项目早期图省事开了nodeIntegration后面想收紧权限时重构成本非常高所以趁项目还小先把这条链路规范起来。3.2 预加载脚本与安全实践预加载脚本是连接主进程和渲染进程的中间层。它在页面加载前运行同时能访问 Node.js API但它的运行环境和页面是隔离的。正因为有了这个隔离机制你才能安全地把能力暴露给页面。安全和开发效率往往是一对矛盾我的建议是保持contextIsolation: true这是 Electron 12 之后的默认值不要轻易改掉。保持nodeIntegration: false禁止页面里直接使用 Node.js 能力。尽量通过contextBridge暴露最小化 API 集不要图省事把整个ipcRenderer或fs模块全挂到全局。对外部加载的内容比如远程 URL要格外小心能不用BrowserWindow加载远程页面就不用。还有一点是关于 CSP如果你加载的页面包含远程资源强烈建议在 index.html 里加上内容安全策略meta http-equivContent-Security-Policy contentdefault-src self; script-src self /这一行能拦截掉不少 XSS 攻击成本很低值得养成熟练工。4. Electron 31 的屏幕分辨率缩放从 DPI 到窗口尺寸的血泪教训4.1 设备像素比与 CSS 像素的错位我在开发一个数据看板时第一次被屏幕缩放问题撞了个结实。用户的电脑是 4K 屏幕Windows 系统缩放设置为 200%Electron 窗口按width: 1280打开结果窗口占满了整个屏幕内部布局还出现了模糊和错位。问题的根源在于 Windows 的 DPI 缩放。Electron 默认会跟着系统缩放走BrowserWindow里的width和height使用的是 CSS 像素但系统缩放到 200% 时一个 CSS 像素会被放大到 2 个物理像素。于是 1280 的逻辑宽度实际占用了 2560 物理像素看起来窗口巨大。要拿到真实的缩放比例可以通过screen模块const { screen } require(electron) const primaryDisplay screen.getPrimaryDisplay() const scaleFactor primaryDisplay.scaleFactor在常见的 100% 缩放下scaleFactor是 1200% 缩放下是 2。这个值直接决定了你看到的窗口尺寸和设备像素比之间的换算关系。4.2 我在缩放问题上踩过的具体坑先说窗口尺寸。如果希望窗口在不同缩放下都保持固定的物理大小可以在创建窗口时把useContentSize和zoomFactor结合起来控制。更常用的做法是监听缩放变化并动态调整const { screen, BrowserWindow } require(electron) function getScaledSize(baseWidth, baseHeight, display) { const factor display.scaleFactor || 1 return { width: Math.round(baseWidth / factor), height: Math.round(baseHeight / factor) } } app.whenReady().then(() { const display screen.getPrimaryDisplay() const { width, height } getScaledSize(1280, 800, display) const win new BrowserWindow({ width, height, autoHideMenuBar: true }) win.loadFile(index.html) })这样做有一个直观的效果同样一个窗口在 100% 缩放的电脑上打开是 1280x800在 200% 缩放的电脑上打开也接近 1280x800 的物理尺寸不会出现“窗口巨大”的问题。第二个坑是屏幕截图和录屏。渲染进程里window.devicePixelRatio拿到的是页面的设备像素比但如果你在截图时没做坐标换算裁剪出来的区域会偏移。我的解决方案是统一以 CSS 像素为业务坐标截图时再按devicePixelRatio放大function capturePage(win) { win.webContents.capturePage() .then((image) { const scale win.webContents.getZoomFactor() || 1 const rect { x: 0, y: 0, width: Math.floor(image.getSize().width / scale), height: Math.floor(image.getSize().height / scale) } // 使用 rect 做后续裁剪 }) }第三个坑是拖拽区域。如果你自定义了标题栏需要给可拖拽区域加上-webkit-app-region: drag但在高分屏下拖拽区域的边缘有时会失灵。原因是缩放后鼠标坐标被换算成了浮点数Electron 的拖拽判定区间可能落在两个像素之间。最简单的规避办法是给拖拽区域留出至少 2px 的余量或者用 CSS 把拖拽区域设置为固定高度不要用百分比。5. 菜单开发从应用菜单到右键菜单5.1 应用菜单与快捷键Electron 默认会提供一个基本的应用菜单包含“文件”“编辑”“视图”“窗口”“帮助”这些标准项。但实际项目中很多应用需要自定义菜单来承载业务功能。通过Menu模块可以做到const { app, Menu } require(electron) function buildMenu() { const template [ { label: 文件, submenu: [ { label: 打开..., accelerator: CmdOrCtrlO, click: () { // 打开文件逻辑 } }, { type: separator }, { label: 退出, role: quit } ] }, { label: 编辑, submenu: [ { role: undo }, { role: redo }, { type: separator }, { role: cut }, { role: copy }, { role: paste } ] } ] const menu Menu.buildFromTemplate(template) Menu.setApplicationMenu(menu) } app.whenReady().then(() { buildMenu() // 再创建窗口 })这里role是 Electron 内置的行为标识比如quit、undo、copy它会自动绑定对应的系统行为和快捷键不需要你手动实现。accelerator字段用来定义快捷键CmdOrCtrlO在 macOS 上对应 CommandO在 Windows/Linux 上对应 CtrlO。自定义菜单时容易忽略的一点是当你设置了自己的应用菜单模板原来的“编辑”菜单里复制粘贴等能力默认就没有了如果你忘了加这些role用户会发现在输入框里无法使用剪贴板快捷键。我就在交付过一个版本后收到反馈“无法复制粘贴”原因就是自定义菜单没有包含copy、paste角色。5.2 右键菜单与动态菜单应用菜单是全局的右键菜单则是针对特定区域或元素的。实现方式也比较直接在渲染进程里监听contextmenu事件再通过 IPC 通知主进程弹出菜单// preload.js contextBridge.exposeInMainWorld(electronAPI, { showContextMenu: () ipcRenderer.send(show-context-menu) })// main.js const { ipcMain, Menu } require(electron) ipcMain.on(show-context-menu, (event) { const template [ { label: 刷新, role: reload }, { label: 复制, role: copy }, { label: 粘贴, role: paste }, { type: separator }, { label: 自定义操作, click: () { // 处理业务逻辑 } } ] const menu Menu.buildFromTemplate(template) menu.popup({ window: BrowserWindow.fromWebContents(event.sender) }) })页面里只需要监听鼠标右键document.addEventListener(contextmenu, (e) { e.preventDefault() window.electronAPI.showContextMenu() })动态菜单的意思是菜单项要根据当前状态比如选中了文本、是否登录、当前页面来变化。做法是在click回调里通过event.sender拿到对应的窗口再向渲染进程询问状态或者干脆在渲染进程里把状态通过 IPC 传出来在主进程里构建菜单前判断一下ipcMain.on(show-context-menu, (event, payload) { const template [] if (payload.hasSelection) { template.push({ label: 复制, role: copy }) } template.push({ label: 粘贴, role: paste }) // ... })这里有个小坑menu.popup调用时要传入正确的窗口引用否则菜单可能弹到别的窗口上。我用BrowserWindow.fromWebContents(event.sender)来保证菜单一定出现在发起请求的那个窗口中这个写法已经很成熟直接抄作业就行。6. 实际开发中容易踩的坑与排查思路6.1 遇到 unable to locate the codex cli binary 这类路径错误时的排查路径在社区里经常能看到类似的报错信息unable to locate the codex cli binary. set codex_cli_path or ensure the electron resources include bin/codex.虽然这条报错文字里带的是 codex但它的本质是“Electron 应用在启动时找不到依赖的外部可执行文件”。这类问题在 Electron 开发中非常典型我把它拆成三层排查路径你遇到类似的报错时可以直接套用。第一层检查环境变量。报错提示里说set codex_cli_path这就说明应用在启动时会读取一个环境变量比如CODEX_CLI_PATH用它去定位外部工具。你在 Shell 里临时设置或者在应用代码里设置环境变量都可以关键是让应用启动时能拿到正确的值。# 临时设置环境变量后启动 export CODEX_CLI_PATH/path/to/codex/bin npm start第二层检查 Electron resources 目录。报错提示里还有一句ensure the electron resources include bin/codex这说明应用期望在那个目录下找到可执行文件。Electron 打包后资源文件会被放在resources目录里。如果你是通过asar打包的还要确认这个可执行文件有没有被打进 asar 里因为 Electron 默认不会把 asar 内的文件当普通文件系统来执行。第三层检查可执行权限。这类问题有时候根本不是路径不对而是文件没有执行权限。尤其是在 macOS 和 Linux 上你从压缩包解压出来的二进制文件可能丢了x权限需要用chmod x补上。chmod x /path/to/codex/bin/codex排查这类问题时我有个习惯在报错堆栈里找到是哪个模块抛出的异常然后直接在模块代码里打日志把解析到的根路径和环境变量值打印出来。这一步能最快定位到“到底是谁找不到谁”而不是看着一大段报错猜测。6.2 打包发布时的常见问题Electron 开发时用npm start跑得很流畅但一打包就出各种幺蛾子这是几乎所有开发者都会经历的过程。我用electron-builder打包时的几个典型问题值得提前避开。一是 native 模块和 node 版本不匹配。如果项目里用了serialport、sqlite3这类原生模块Electron 的 Node.js 版本和系统 Node.js 版本可能不同编译出来的.node文件不能直接用。解决方案是在项目里统一用electron-rebuild重新编译npx electron-rebuild -f -w serialport二是文件路径问题。开发模式下__dirname指向的是源码目录打包后代码在 asar 里__dirname会指向 asar 内的虚拟路径。很多新手在fs.readFile时写死资源路径打包后就找不到文件。更好的做法是用app.getAppPath()获取应用根目录或者把资源放到process.resourcesPath下面。这里有一条我最常提醒自己的规则代码里不要用硬编码相对路径去读配置文件应该走app.getPath(userData)来放用户数据。三是图标问题。Windows 需要.ico文件macOS 需要.icns文件Linux 则需要多个尺寸的 PNG。electron-builder 在打包时会校验图标格式如果你只给了一个 PNG它可能直接报错或者生成一个默认图标。我的建议是准备一套完整的图标资源从 16x16 到 512x512都放到build/目录下并在package.json里配置好build: { appId: com.example.app, files: [dist/**/*, main.js, package.json], win: { icon: build/icon.ico }, mac: { icon: build/icon.icns } }四是自动更新的坑。如果你接了自动更新一定要区分开发环境和生产环境的更新地址。我曾经因为没区分在开发时不断触发更新弹窗排查了很久才发现是更新服务器配置里写死了生产地址开发环境的应用也去请求它而版本号刚好满足更新条件。后来我统一走环境变量来控制更新地址开发环境直接关掉自动更新这个问题才算彻底解决。7. 继续扩展的方向从工具型应用到成熟桌面产品7.1 自动更新Electron 应用想要真正面向用户自动更新几乎是标配。官方方案是electron-updater它能帮你检查更新、下载安装包、静默安装。配置上需要指定一个更新服务器地址同时代码里要区分开发环境和生产环境const { autoUpdater } require(electron-updater) if (process.env.NODE_ENV production) { autoUpdater.checkForUpdatesAndNotify() }这里有个前置条件你的安装包必须是用 electron-builder 等工具正确构建出来的且版本号比已安装版本更高更新才能生效。开发模式下checkForUpdatesAndNotify大概率会报错或者跳过。7.2 后续扩展建议Electron 的生态已经相当成熟如果你打算把它用于长期项目我有三个方向性的建议。第一个方向是性能优化。应用启动速度主要取决于主进程代码质量和渲染进程页面大小建议用webpack或vite对渲染进程代码做拆包和压缩。主进程初始化里不要加载不必要的模块能用懒加载就用懒加载。第二个方向是构建流程标准化。把开发、构建、测试、发布这些环节用脚本串起来我在项目里用 GitHub Actions 做多平台打包配置不算复杂但能省去大量手动操作。第三个方向是持续跟进 Electron 升级。每一个大版本都会带来性能和稳定性改进。Electron 作为一个底层依赖升级时要重点回归窗口、IPC、菜单这些核心路径。建议每隔两个大版本就评估一次升级计划长期停在旧版本会让安全补丁和技术债越积越多。这一路走过来我的体会是 Electron 入门本身不难只要先把主进程、渲染进程、IPC 这三条主线理清楚再动手做一个小工具练手大概两周就能从零写出一个能跑通的应用。难的是在后续迭代里养成安全意识和排查问题的系统性思路。希望这篇教程能让你在起步阶段少走一些弯路把踩坑的精力省下来花在真正有产品价值的地方。最后分享一个我坚持了很久的习惯每个 Electron 项目从第一天起就建一个docs/troubleshooting.md把每次踩坑的原因、报错信息和解决步骤都记录下来。三个月后回头看这个文档比很多教程都有用——因为你记录下来的都是你真实环境和真实业务里发生过的坑而在社区和文档里你未必能直接搜到答案。