★ FEATURED ARTICLE 第一次看到这个项目代号时我也愣了一下。rea这三个字母没有 README 说明没有设计文档一搜代码才发现里面的注释写得很清楚REA React Electron App。这是一个用 Electron 做壳、React 做渲染层的跨平台桌面应用项目代号直接取自三个关键词的首字母。说实话这种名字起得很随意但骨架和工程化程度却很扎实。这类项目在当下的桌面端开发里很常见想用前端技术栈覆盖 Windows、macOS、Linux 三端又不想为每个平台单独维护一套原生代码Electron 依然是成本最低、生态最成熟的方案。如果你也打算做一个桌面工具类应用或者正在纠结“前端技术能不能做桌面软件”“打包流程怎么搭”那这篇内容应该能帮你少踩不少坑。我会围绕这个rea项目的实际结构把选型理由、目录设计、主进程与渲染进程的通信方式、打包发布和常见问题一次讲清楚。1. 项目定位与选型思路为什么还是 Electron React1.1 跨平台桌面方案的真实权衡很多人一聊桌面开发第一个疑问就是“现在不是有 Tauri 吗为什么还选 Electron”。我在搭建 REA 时确实把市面上的主流方案拉出来对比过一遍。Tauri 的优势在包体积和内存占用但它要求后端使用 Rust团队里没人写过 Rust学习成本立刻翻倍而且它在 Windows 上依赖 WebView2在某些精简版系统上还得先处理运行时缺失的问题。Flutter Desktop 能编出漂亮的 UI但要在现有 React 生态里做数据层整合等于把整个团队的技术栈换掉。Electron 的取舍在我看来非常现实虽然每个包至少 80MB 起步但它把 Chromium 和 Node.js 都塞进了应用本体意味着渲染层表现稳定、系统兼容性可控、前端资源可以直接复用。对一个需要快速交付、又要长期维护的工具型桌面应用来说这套组合最稳。1.2 REA 的核心功能边界这个项目的定位不是那种大而全的办公套件而是一个内部效率工具左侧导航、右侧内容区支持本地数据持久化能通过系统托盘常驻后台收到某些事件时弹出系统通知。整体功能点不复杂但它要求“安静地待在后台”这对 Electron 应用的进程生命周期管理就提出了要求。所以 REA 的核心架构可以抽象成三块主进程负责窗口创建、托盘、生命周期和本地数据读写渲染进程负责界面交互preload 脚本负责在两者之间搭一座安全的桥。后续你要扩展任何功能基本都把代码塞进这三块中的某一处边界清晰不会乱。1.3 适合谁参考这套代码如果你想做一个自己的桌面便签、定时提醒工具或者帮团队写一个内部数据查询面板REA 的代码结构可以作为起点。它对 Electron 版本、React 版本都做了锁定不追求花哨而是把主进程、preload、渲染层分开编译开发模式下热更新生产模式下打成安装包整套流程是可以直接照搬的。2. 工程结构拆解三层职责划分与安全基线2.1 目录结构设计按照 REA 的实际布局项目里没有把所有代码堆进src而是分出了electron目录和src目录electron内部再按主进程、preload、共享类型分开rea ├── package.json ├── electron │ ├── main │ │ ├── index.ts // 主进程入口 │ │ ├── window.ts // 窗口创建与配置 │ │ ├── tray.ts // 托盘逻辑 │ │ └── storage.ts // 本地数据读写 │ ├── preload │ │ └── index.ts // 暴露给渲染层的 API │ └── shared │ └── ipc.ts // IPC 通道名与类型定义 ├── src │ ├── main.tsx │ ├── App.tsx │ ├── pages │ └── components └── dist // 渲染层构建产物之所以把主进程和 preload 独立出来是因为 Electron 在有 contextIsolation 开启的情况下渲染进程不能直接访问 Node.js API必须依赖 preload 里的contextBridge。这种情况下一个electron顶层目录让编译配置更清晰也避免别人接手时把主进程代码和 React 组件混在一起。2.2 IPC 通道命名与类型约束长时间维护 Electron 项目的人都知道最容易出 bug 的地方就是 IPC 通信通道名字写错一个字回调就静默失败。REA 采取了一个很朴素的办法在electon/shared/ipc.ts里把通道名统一导出来export const IPC { DATA_SAVE: data:save, DATA_LOAD: data:load, APP_VERSION: app:version, WINDOW_MINIMIZE: window:minimize, WINDOW_CLOSE: window:close, } as const主进程和 preload 都从这份常量里取值渲染层再通过window.rea调用。通道名用命名空间:动作的格式能一眼看出这组消息是哪个业务域的。对于通道数量超过 20 个的项目我还会在 shared 里补类型定义但 REA 的体量还不需要常量表就够用了。2.3 安全基线不能省创建 BrowserWindow 时下面这几项不是可选项而是必须项new BrowserWindow({ width: 1200, height: 800, webPreferences: { preload: path.join(__dirname, ../preload/index.js), contextIsolation: true, nodeIntegration: false, sandbox: true, }, })sandbox: true会让 preload 脚本运行在受限环境里能够使用的是contextBridge和ipcRenderer的一小部分方法其他 Node 能力都被关掉了。这意味着即使页面被注入了一段恶意脚本它也拿不到系统权限。有同事为了省事把nodeIntegration: true开起来后来页面加载第三方资源时出现了安全告警又花时间排查得不偿失。3. 主进程生命周期与多窗口管理3.1 入口文件里最该注意的时机主进程入口的代码量不大但每个回调的顺序都影响用户体验。REA 的做法是app.whenReady().then(() { createMainWindow() createTray() }) app.on(window-all-closed, () { if (process.platform ! darwin) { app.quit() } }) app.on(activate, () { if (BrowserWindow.getAllWindows().length 0) { createMainWindow() } })这套逻辑覆盖了三个关键场景应用启动后创建主窗口所有窗口关闭后在 Windows 和 Linux 上退出进程但在 macOS 上保留因为 macOS 的应用通常不因为窗口关完就退出点击 Dock 图标时恢复窗口。很多 Electron 应用在 mac 上表现奇怪就是因为没有处理activate事件。3.2 窗口出现前的“白色闪烁”问题一个新打开的 Electron 窗口如果直接loadFile或loadURL用户在页面渲染出来之前会看到一片白屏感官上像卡住了。REA 的处理是在ready-to-show之后再show()const win new BrowserWindow({ ..., show: false }) win.once(ready-to-show, () { win.show() })这一处小小的改动让窗口从“突然蹦出来”变成“准备好了再展示”每次打开都觉得流畅很多。如果你发现窗口加载速度还是慢可以把backgroundColor设置成和页面底色一致进一步降低视觉突兀感。3.3 托盘和最小化策略REA 作为常驻后台的工具点击关闭按钮时不应该让应用彻底退出而是隐藏到托盘。实现思路并不复杂拦截窗口的close事件判断是否允许退出。let isQuitting false win.on(close, (event) { if (!isQuitting) { event.preventDefault() win.hide() } }) // 托盘菜单里选择“退出”时 function quitApp() { isQuitting true app.quit() }创建托盘时菜单里至少要有“显示主界面”和“退出”两项。图标文件要特别注意路径问题开发时用项目里的资源路径打包后要用process.resourcesPath否则菜单都弹出来了图标却显示成默认空白。4. 渲染层与本地数据持久化4.1 preload 暴露的窗口 API渲染层拿不到 Node 能力只能调用 preload 暴露出来的有限 APIimport { contextBridge, ipcRenderer } from electron const api { saveData: (key: string, value: unknown) ipcRenderer.invoke(IPC.DATA_SAVE, key, value), loadData: (key: string) ipcRenderer.invoke(IPC.DATA_LOAD, key), getAppVersion: () ipcRenderer.invoke(IPC.APP_VERSION), minimizeWindow: () ipcRenderer.send(IPC.WINDOW_MINIMIZE), closeWindow: () ipcRenderer.send(IPC.WINDOW_CLOSE), } contextBridge.exposeInMainWorld(rea, api)这里统一用invoke/handle模式来处理有返回值的请求用send/on模式来处理单向通知。遇到只需要“触发一个行为”的 IPC不要用invoke否则主进程必须每条都回消息逻辑上绕了一大圈。4.2 数据存在哪主进程直接写 JSONElectron 的localStorage当然能用但它和某个窗口的 session 绑定用户清缓存时容易误伤。REA 把持久化安排在主进程通过 IPC 读一个 JSON 文件import { app } from electron import fs from node:fs import path from node:path const dataFile path.join(app.getPath(userData), data.json) export function readData() { if (!fs.existsSync(dataFile)) return {} try { return JSON.parse(fs.readFileSync(dataFile, utf-8)) } catch { return {} } } export function writeData(key: string, value: unknown) { const all readData() all[key] value fs.writeFileSync(dataFile, JSON.stringify(all, null, 2)) }app.getPath(userData)在不同操作系统上会落到各自的用户数据目录不需要自己拼系统路径。写文件时用同步 API 在低频场景下没问题但如果你要频繁保存就得改成异步队列避免主进程卡顿。4.3 对复杂数据的处理建议JSON 文件方案适合配置类和轻量业务数据数据量大了以后会很吃力。我后来在另一个项目里遇到单文件超过 20 万的记录读写明显变慢最后还是换成了 SQLite。REA 当前的数据量完全在 JSON 的舒适区等需要按字段查询、做索引或事务的时候再引入原生 SQLite 模块也不迟不要一开始就上重型依赖。5. 开发模式与打包发布流程5.1 开发环境下的双进程启动REA 的开发模式很典型Vite 负责渲染层的 dev servertsc 负责编译主进程和 preload。你不可能等 cd 进去再手动跑两个命令所以package.json里要么用 concurrently 打包两个命令要么直接用 electron-vite 这种一体化工具。我用的是前者{ scripts: { dev:renderer: vite, dev:electron: tsc -p electron/tsconfig.json cross-env NODE_ENVdevelopment electron ., dev: concurrently -k \npm run dev:renderer\ \npm run dev:electron\ } }主进程里通过环境变量区分加载方式if (process.env.NODE_ENV development) { win.loadURL(http://localhost:5173) } else { win.loadFile(path.join(__dirname, ../dist/index.html)) }这个判断看起来简单但它是开发模式下热更新、生产模式下正常加载的关键。我见过有人把loadFile的路径写错开发环境一切正常打包后白屏最后发现是dist相对路径算错了层级。5.2 electron-builder 的核心配置REA 用 electron-builder 出安装包。一个相对精简的配置长这样{ appId: com.example.rea, productName: REA, files: [ dist/**/*, electron-dist/**/* ], directories: { output: release }, asar: true, win: { target: [nsis] }, mac: { target: [dmg], category: public.app-category.productivity }, nsis: { oneClick: false, allowToChangeInstallationDirectory: true, createDesktopShortcut: true } }这里有几个容易出错的点。files必须同时包含渲染层产物和主进程编译产物少一个打包出来就缺文件。asar: true默认开启开启后代码被打进app.asar能减少文件数量、提升启动速度。调试时如果怀疑某个文件没打进去可以在主进程里临时关掉 asar重新打包后直接看目录结构。5.3 安装包体积优化经验Electron 应用动辄上百兆REA 做过一轮优化效果很直接生产依赖只留运行时需要的Electron 打包器会按dependencies里的依赖收集devDependencies里的内容不能出现在运行时否则会被当垃圾打进包里。渲染层做路由懒加载。页面多的时候把所有页面一次性打进一个 bundle体积暴涨且首屏变慢。REA 的页面不多但这个习惯保留了。图标资源压缩。托盘和窗口图标是应用的门面但不能直接塞几 MB 的 PNG。建议导出多个尺寸、压缩后再放进资源目录。分析依赖占用。用 source-map-explorer 或 rollup-plugin-visualizer 查一下每个依赖占了多少字节往往能发现某个不起眼的工具库占了 40%替换掉就能瘦身不少。做完整套优化后一个空壳 Electron 的基线大约 80MBUI 层再压到几 MB 的量级整个安装包能控制在 90MB 左右。如果还要更极端就得考虑换 Tauri 了但那是另一个技术话题。6. 常见问题与排查技巧实录6.1 npm 安装 Electron 慢到怀疑人生首次npm install electron默认要从国外服务器下二进制包很多人卡在这一步。解决办法不是换 npm 源而是要单独设置 Electron 的镜像源npm config set electron_mirror https://npmmirror.com/mirrors/electron/设置完需要删除 node_modules 重新安装或者至少npm cache clean --force再装一次。这个变量只影响 Electron 下载不影响其他包可以放心配置。6.2 IPC 调用的返回值永远是 undefined写着win.webContents.send(data:load)渲染层ipcRenderer.on(data:load, ...)怎么等都等不到数据这是最常见的问题。原因大概率是用了单向的send而数据返回值需要通过event.reply发回来。REA 里的统一方案是所有“要拿数据”的通信都改成invokeipcMain.handle单方向通知才用send。6.3 开发环境正常打包后白屏这类问题十有八九是文件路径错误。Electron 打包后代码在app.asar里__dirname指向的是解包后的虚拟路径结构不要试图直接访问../dist/index.html之外的相对路径。排查步骤是判断是否loadFile失败打开开发者工具看主进程报错。确认files配置是否把 dist 和 electron 产物都包含进来。在win.webContents.openDevTools()里看渲染层的网络请求如果 index.html 都 404那就是路径问题。6.4 窗口关了但进程还活着在 Windows 上用户把所有窗口关掉你期待程序退出但它还在任务管理器里躺着。检查是否有未取消的托盘应用、是否有window-all-closed事件被覆盖或者有些异步回调还在引用窗口对象。REA 的做法是在窗口关闭后显式清掉托盘引用再配合app.quit()同时注册before-quit做最后清理。6.5 系统通知不弹Electron 的 Notification 在不同平台上的权限要求不一样。开发模式下 macOS 会给 Electron 应用通知权限但打包后的应用如果没有正确签名通知可能被系统静默拦截。Windows 上需要确认系统通知开关是开启的。如果代码逻辑没问题先换个平台试试能快速定位是不是系统权限层面的问题。7. 后续扩展方向与维护建议rea这个项目做完第一版之后我给它留了几个扩展口子都是实际后续新增功能时用到的自动更新集成 electron-updater配置好更新服务器地址主进程启动时检查一次需要通过安全通道下载更新包。崩溃日志在render-process-gone和unhandled-rejection回调里把堆栈写到本地日志文件方便用户反馈问题时快速定位。本地数据库数据量开始变大后把 JSON 文件切换到 SQLite 或 DEXIE 封装的 IndexedDB尽量不在主进程里做复杂查询。菜单栏快捷键用globalShortcut注册全局快捷键适合快速唤出应用的小窗口。维护期最需要注意的是版本升级。Electron 的主版本升级经常伴随 API 变更尤其在webPreferences默认值上小版本升级也可能改变行为所以每次升级后至少要在三端跑一遍核心流程再发布。package.json里能锁住精确版本就锁住不推荐用^号随意浮动。最后分享一个自己的习惯每次打开这类项目我会先把package.json过一遍看看依赖版本、脚本命令、打包配置是否对得上然后读主进程入口文件理解它怎么管理窗口和生命周期。项目代号再随意只要基础结构是清晰的后续维护成本就不会高。REA 这个名字虽只三个字母但把一个桌面应用从零到打包发布的关键环节都走了一遍作为模板和练手项目都挺值。
阅读完成 · 觉得有帮助？
