Vue3+TS+ElementPlus+Vite构建Electron桌面应用实践

最近又用 vue3 ts elementPlus vite 这套组合整整搭了一遍 electron 桌面端应用从初始化到打包上线踩了不少坑也顺手把几个老折腾人的问题彻底理清了。这篇东西不聊虚的直接把我验证过能跑通的方案、配置代码和排错思路完整记录下来。无论你是刚接触 electron 的新手还是已经写过不少 vue 后端页面、第一次想转为桌面应用的开发者这套方案都值得参考。它能解决的核心问题很明确如何用一套前端技术栈同时兼顾 web 端的开发效率与桌面端的原生能力同时避开 vite 与 node 环境之间那些最典型的冲突。我默认你已经对 vue 的基础语法有一定了解ts 至少写过几个文件electron 是什么有一点模糊概念但没完整搞过。这样节奏刚好太基础的我不铺开讲太深的主进程源码剖析也不做重点放在“能落地、能打包、能持续维护”这条主线上。1. 先把整套方案的架构捋清楚1.1 为什么是这四个工具组合在一起很多人在看到“vue3 ts elementPlus vite electron”这一长串词的时候第一反应是“这到底谁管谁”。我习惯用一个房子来打比方electron 是整个毛坯房决定了房子的骨架和水电布局vue3 是室内的装修设计决定了每个房间长什么样ts 是装修图纸上的标注规范让每个尺寸和材料都有明确的类型约束vite 是施工队伍里的高效工具负责把图纸快速变成实际效果elementPlus 则是已经造好的标准化家具直接搬进来就能用。这套组合里的每一环都不是随便选的。vue3 的 composition API 配合 ts 的类型推导写业务逻辑的时候比 vue2 时期舒服得多尤其是状态一多、交互一变复杂类型系统能帮你拦住一大批低级错误。elementPlus 本身就是用 ts 写的和 vue3 的契合度天然高做后台管理类界面几乎就是开箱即用。vite 的开发服务器冷启动速度快、热更新快这在 electron 开发场景里非常重要因为渲染进程每次改动都要刷新界面如果构建工具慢整个开发节奏会被拖垮。1.2 理解 electron 的进程模型是后面所有操作的基础这一节我必须放在最前面说因为后面所有“诡异报错”都源自主进程和渲染进程之间的关系没理顺。electron 应用启动后至少会拉起两个进程主进程main process负责创建窗口、调用系统原生能力、管理应用生命周期渲染进程renderer process负责加载你的 vue 页面并展示给用户。主进程运行在 node.js 环境里能使用 fs、os、path 等所有 node 模块渲染进程则本质上是浏览器环境默认情况下不能直接访问 node API。两者之间通过 ipcInter-Process Communication进行消息通信。最早期的 electron 写法喜欢直接在渲染进程里开 nodeIntegration 开关这样页面里的 js 就能直接用 require 和 process确实省事但安全风险极大。现在官方推荐的方案是主进程保持完整 node 能力渲染进程保持浏览器纯净中间加一层 preload 脚本通过 contextBridge 把需要暴露给页面的能力按白名单方式传递过去。你可以把 preload 理解成酒店前台的对讲机住客渲染进程不能直接去后厨主进程拿菜而是通过对讲机点单后厨做好再从窗口递出来。ipc 通信就是这个对讲系统contextBridge 则规定了哪些菜可以点、哪些区域不能进。这套模型一旦在脑子里清晰了后面所有配置项的取舍就都有了判断依据。2. 环境准备与脚手架搭建2.1 版本选择与踩过的坑版本问题看着不起眼却是绝大多数“照着教程做却报错”的根源。electron 迭代非常快vue 和 vite 也在持续更新相互之间如果不匹配常常是 npm 装了一堆依赖跑起来第一天就报错。我当前验证过的一套稳定组合是node 18 以上、vue 3.4、vite 5.x、typescript 5.3、electron 28、elementPlus 2.5。这几套版本搭配在一起无论是开发时跑 vite 还是后期 electron-builder 打包都没有明显的兼容性问题。不少人会掉进一个坑直接用 create-electron-app 这类老脚手架生成项目结果发现里面是 webpack 时代的配置或者自带的 electron 版本太旧与 vue 3 生态脱节。我更推荐手动组装虽然多花十几分钟但每一步的配置都在自己掌控之下出了问题也更容易定位。如果觉得手动麻烦也可以参考 electron-vite 社区方案它把主进程、preload、渲染进程三部分的构建统一管理起来但前提是你已经理解手动搭建的逻辑否则出了问题很难排查。2.2 从零搭建的具体步骤与目录结构先创建 vue 项目基础骨架在命令行里执行npm create vuelatest electron-vue-demo选择安装 typescript、jsx 支持路由器按需选。这一步生成的只是渲染进程部分electron 还需要单独引入。接着安装依赖cd electron-vue-demo npm install npm install element-plus npm install -D electron electron-builder concurrently wait-on这里的 concurrently 用来同时启动 vite 和 electronwait-on 用于等待 vite 开发服务器就绪后再拉起 electron否则 electron 窗口启动时页面还没编译完白屏几秒容易误判为故障。安装完成后在项目根目录新建 electron 文件夹里面放两个文件main.ts 作为主进程入口preload.ts 作为预加载脚本。同时把 vite 的构建输出调整成相对路径避免打包后 file:// 协议下资源加载失败。最终目录结构大概是这样的electron-vue-demo ├─ electron │ ├─ main.ts │ └─ preload.ts ├─ src │ ├─ components │ ├─ views │ ├─ App.vue │ ├─ main.ts │ └─ vite-env.d.ts ├─ index.html ├─ package.json ├─ tsconfig.json └─ vite.config.tspackage.json 里需要加两个 dev 脚本一个用于同时启动 vite 和 electron另一个用于打包。我自己习惯用一个 start 脚本搞定scripts: { dev: concurrently -k \npm run dev:vite\ \npm run dev:electron\, dev:vite: vite, dev:electron: wait-on tcp:5173 electron ., build: vue-tsc vite build electron-builder }这里有个细节值得注意electron 主进程入口默认读取 package.json 里的 main 字段我把它指向 dist-electron/main.js。因为主进程代码用 ts 编写需要先编译成 js。最简单的方式是用 esbuild 或者 tsc 单独编译 electron 目录我为了少引入一个工具链直接用 tsc 编译命令类似于tsc -p electron/tsconfig.json在 build 前执行即可。3. 关键配置Vite 与 TS 的桌面端适配3.1 解决 process is not defined 的技术原理这是很多人在 vite electron 项目里遇到的第一个报错几乎每搜索一次就能看到一遍。报错的场景一般是在某个 src 下的组件里写了console.log(process.env.NODE_ENV)或者某个依赖库内部访问了 process 全局变量运行后浏览器控制台直接报process is not defined。原因其实不复杂vite 在构建渲染进程代码时默认目标环境是浏览器。浏览器是没有 node 的 process 全局对象的。而 electron 开发模式下渲染进程虽然跑在 chromium 里但不少人开了 nodeIntegration 之后误以为它拥有完整的 node 能力结果在项目代码里直接使用 process打包出来到浏览器环境就崩了。真正干净的解决办法是渲染进程的代码不要直接访问任何 node 全局变量凡是需要主进程能力的地方一律通过 preload 暴露出来的接口去调用。如果确实有某个依赖库在浏览器环境里访问了 process那就在 vite.config.ts 里给它一个兜底的空实现或安全实现例如// vite.config.ts export default defineConfig({ define: { process.env: {} } })这个配置的作用是在打包时把所有process.env替换成空对象避免运行时找不到全局变量。但这只是兼容手段不能作为常规写法依赖。核心原则还是前面说的那条渲染层保持纯净。preload 和主进程才是和 node 打交道的地方。3.2 vite 不识别 buffer 的处理思路另一个高频报错是 buffer 相关。比如页面里使用了Buffer.from(...)或某个依赖内部调用了 Buffervite 构建时直接提示 buffer is not defined甚至有的报错会指向 Browserify 的 polyfill 问题。这正是 electron 项目和纯 web 项目不同的地方web 项目里前端代码根本不需要 Buffer桌面端应用处理文件内容、二进制数据时却很容易碰到。推荐的做法是把 Buffer 相关逻辑放到主进程或 preload 里处理。比如读取文件、解析二进制流这类操作本来就该在主进程完成渲染层只负责传入路径和接收结果。这样做既贴合 electron 的架构安全要求也绕开了 vite 打包时的 node 全局缺失问题。如果只是因为某个第三方库在渲染层依赖了 Buffer可以在 vite 配置里用 esbuild 的 define 临时替换或者使用社区提供的 buffer polyfill 插件但这属于打补丁后期升级依赖容易失效我不建议长期依赖。3.3 TS 类型声明与 window 上自定义 API 的类型定义用 ts 写 electron 渲染层还有一个绕不开的事项preload 通过 contextBridge 暴露出来的 API是挂在 window 对象上的自定义属性ts 默认并不知道它的存在。如果你在组件里写window.api.xxx()编辑器会立即报类型错误。解决方法是新建一个类型声明文件手动扩展 Window 接口。// src/types/electron.d.ts export interface ElectronApi { readFile: (path: string) Promisestring writeFile: (path: string, content: string) Promiseboolean } declare global { interface Window { api: ElectronApi } } export {}这个文件被 tsconfig 包含后整个项目的类型提示就完整了。这里我踩过一次坑直接在 .ts 文件里 declare global 而不是放在 .d.ts 里结果 ts-node 编译时始终不生效后来改成 .d.ts 并在 tsconfig 的 include 中加入 src 目录才解决。如果你用的 vue-tsc 构建同样要注意 types 字段中不要漏掉 vite/client否则 import.meta.env 的类型也会报错。4. 主进程与渲染进程的通信实现4.1 安全的上下文隔离配置聊到通信先重申一遍安全基线。创建 BrowserWindow 时必须显式设置两个关键的布尔值contextIsolation 为 truenodeIntegration 为 false。前者表示渲染进程运行在独立的 JavaScript 上下文中preload 中暴露的 API 不会直接污染页面全局后者表示页面代码无法直接使用 node 的 require 与 process 等能力。// electron/main.ts const win new BrowserWindow({ width: 1200, height: 800, webPreferences: { preload: path.join(__dirname, ../preload.js), contextIsolation: true, nodeIntegration: false } })preload 脚本里通过 contextBridge 暴露一个精简的接口对象。不要直接暴露整个 ipcRenderer而是手动定义每个方法这样可以在暴露层做参数校验避免渲染层拿到过大的权限后误操作。从我实际经验看参数校验非常重要因为桌面应用和 web 页面不同渲染层可能被注入恶意代码而主进程的某些接口涉及文件系统读写一旦被滥用后果严重。4.2 用 ipcMain.handle 与 ipcRenderer.invoke 实现双向调用主进程与渲染进程通信有两对经典组合ipcMain.handle ipcRenderer.invoke用于请求响应模式适合“渲染层发起、主进程处理并返回结果”ipcMain.on ipcRenderer.send用于单向推送模式适合主进程主动发消息给渲染层。平时百分之八十以上的业务场景用前一对就够了因为它天然支持 Promise代码写起来和普通函数调用几乎没有区别而且异常能沿着 Promise 链传播回来。主进程侧在 app ready 之后注册处理函数// electron/main.ts import { ipcMain, app } from electron import fs from fs/promises ipcMain.handle(file:read, async (_event, filePath: string) { const content await fs.readFile(filePath, utf-8) return content })preload 侧把这个能力暴露成安全、独立的函数// electron/preload.ts import { contextBridge, ipcRenderer } from electron contextBridge.exposeInMainWorld(api, { readFile: (filePath: string) ipcRenderer.invoke(file:read, filePath) })渲染层调用时就像调用一个本地异步函数如果主进程抛出了异常渲染层也能通过 try-catch 捕获到。这种模式下不需要手动处理事件监听和清理不需要自定义回调函数整体代码量更少心智负担也更低。4.3 给通信层封装类型安全的调用封装主进程和渲染进程之间的消息通道是跨进程的字符串协议ts 的类型检查并不能自动保证两边的一致性。比如主进程定义了 handle(file:read) 返回 string渲染层如果把它当 number 用ts 不会报错但运行时就会有问题。我的做法是抽出一份共享类型定义文件同时被主进程、preload 和渲染层引用保证通道名和参数两头对齐。共享类型的文件比如shared/ipc-types.ts// shared/ipc-types.ts export interface IpcApi { readFile(filePath: string): Promisestring writeFile(filePath: string, content: string): Promiseboolean getAppVersion(): Promisestring }然后让 preload 的暴露对象严格实现这个接口。渲染层再用一个包装模块把 window.api 的类型断言为 IpcApi这样全链路类型都是完整的。好处是后期改一个通道名或参数结构ts 会立刻把所有调用点都标出来省去满项目搜索字符串的麻烦。对于稍大一点的项目这个成本非常值得前期投入。5. Element Plus 集成与桌面端界面适配5.1 按需引入与自动导入的配置方式Element Plus 官方文档提供了两种引入方式全量引入和按需引入。桌面端应用不像 web 那样需要极度压缩资源毕竟跑在用户本地但打包体积依然会影响安装包大小按需引入依然有意义。我的做法是用 unplugin-auto-import 和 unplugin-vue-components 这两个插件实现组件自动导入同时额外配置 ElementPlusResolver这样在模板里直接写 el-button、el-table连 import 语句都不用写。// vite.config.ts import AutoImport from unplugin-auto-import/vite import Components from unplugin-vue-components/vite import { ElementPlusResolver } from unplugin-vue-components/resolvers export default defineConfig({ plugins: [ vue(), AutoImport({ resolvers: [ElementPlusResolver()] }), Components({ resolvers: [ElementPlusResolver()] }) ] })这里要注意一个来自实战的坑自动导入生成的两个文件 auto-imports.d.ts 和 components.d.ts默认放在项目根目录需要确保它们被 tsconfig 包含。如果没包含编辑器不会红报错但 vue-tsc 构建时会提示找不到对应的类型声明我第一次遇到时以为是插件版本问题排查了半小时才发现是 tsconfig 的 include 太窄。5.2 自定义无边框窗口与拖拽区域的处理桌面端应用和网页最大的视觉区别就是通常没有浏览器地址栏和标签栏。很多 electron 应用会自定义一个标题栏这需要把 BrowserWindow 的 frame 参数设为 false完全隐藏系统窗口边框然后在页面里自绘顶部栏。自定义标题栏最烦的是拖拽区域CSS 里可以这样处理.title-bar { -webkit-app-region: drag; height: 48px; background: #1e1e2e; } .title-bar button { -webkit-app-region: no-drag; }如果整个标题栏都设成 drag那上面的最小化和关闭按钮就全部点不动了所以按钮元素必须覆盖为 no-drag。另一个容易踩的坑是双击拖拽区域时窗口不会自动最大化需要额外监听 double-click 事件并通过 ipc 通知主进程执行最大化/还原操作。这类窗口控制能力属于主进程职责所以同样要走 ipc 通道。5.3 页面里使用 node 能力的正确姿势事实上在 vue 页面里直接import { ipcRenderer } from electron是新手最容易犯的错误之一。因为 electron 在渲染层并不是标准的 node 包导入方式加上 vite 构建时根本不会处理 electron 模块的浏览器端引入结果往往会得到 undefined 或直接构建失败。正确的姿势永远是页面里只依赖 window.api 上暴露的固定方法不在渲染层 import electron 的任何东西。我在自己的项目里所有页面组件都遵循这条约束连文件名和注释都在强调这一点。这个纪律不光是技术正确性问题更是安全边界问题。渲染层是无辜的只要保证它拿到的是白名单能力就算页面被注入恶意脚本它能造成的破坏也极其有限。6. 常见问题排查与打包优化实录6.1 高频报错问题速查表我把这段时间实际遇到的、以及身边同事问得最多的问题整理成了速查表方便大家直接对号入座问题现象根本原因解决思路渲染层报 process is not definedvite 目标环境是浏览器缺少 node 全局对象渲染层不直接访问 process必要时在 vite define 中提供兜底渲染层报 buffer is not definedBrowserify polyfill 未配置且浏览器无 BufferBuffer 相关逻辑放到主进程渲染层用共享 API 调用window.api 为 undefinedpreload 路径配置错误或 contextIsolation 设置异常检查 webPreferences 中 preload 路径是否正确开发时窗口白屏vite dev server 未就绪electron 提前启动使用 wait-on 等待端口再启动 electron打包后资源加载失败页面内引用了绝对路径设置 vite 的 base 为 ./elementPlus 组件样式加载异常自动导入生成文件未被 tsconfig 包含检查 tsconfig include 是否覆盖根目录的 .d.ts 文件关闭按钮失效或最小化异常css 中 drag 区域覆盖了按钮按钮上显式设置 no-drag并触发主进程控制6.2 打包体积优化与 electron-builder 配置要点用 electron-builder 打安装包第一次跑起来会让人怀疑人生一个简单应用安装包轻轻松松超过 100MB。这里面大头是 chromium 内核和 node 运行时无法避免。但可以优化的是业务代码和依赖体积。我在配置中会把 node_modules 里纯开发期的工具排除掉比如 vite、typescript、electron 本身都不应该进最终的 asar 包。electron-builder.yml 的核心配置大致如下appId: com.example.demo productName: DemoApp directories: output: release files: - dist/**/* - dist-electron/**/* - package.json asar: true win: target: - nsis nsis: oneClick: false perMachine: false allowToChangeInstallationDirectory: true关键点是 files 白名单只保留构建产物和 package.json。如果误把 src 目录或 node_modules 全部打进去包内会有大量无用文件安装体积和启动速度都会受影响。同时建议开启 asar 打包它能把应用文件打包成一个归档文件既减少了文件数量又防止业务代码被轻易篡改。6.3 内存优化与强制垃圾回收的实操经常有人问我 electron 应用用久了内存为什么会越涨越高。这里有个关键背景electron 底层的 chromium 自带了高效的垃圾回收机制但某些长时间运行的操作尤其是大量 dom 节点更新或复杂 canvas 绘制可能会导致内存回收不及时。一个可行的优化办法是给 electron 主进程开启 expose-gc 参数配合定时调用 global.gc() 来主动触发垃圾回收。实际配置方式是启动时通过 app.commandLine.appendSwitch 写入// electron/main.ts app.commandLine.appendSwitch(js-flags, --expose-gc)然后在主进程里获取 GC 句柄结合 app.getAppMetrics() 做周期性的健康检查setInterval(() { const gc (global as any).gc if (typeof gc function) { gc() } const metrics app.getAppMetrics() metrics.forEach((metric) { console.log(进程 PID: ${metric.pid}, 内存: ${metric.memory.workingSetSize / 1024 / 1024} MB) }) }, 30000)但这里必须说明一点主动触发 gc 是优化手段不是万能药。如果发现内存持续上涨并伴随明显卡顿更应该排查是否存在事件监听器泄漏、定时器未清理、全局引用导致的对象不可回收等问题。js-flags 的方式适合在发布版本中开启用来缓解内存回收不及时的现象但根因还是得靠代码层面解决。6.4 开发过程中的两个效率小技巧最后说两个直接影响开发体验的小技巧。第一个electron 主进程代码改动后是需要重启才生效的但 vite 只热更新渲染进程。常规做法是用 nodemon 监听 electron 目录的文件变化并自动重启 electron我实际用下来比手动重启舒服得多唯一要注意的是 nodemon 重启 electron 前要先杀掉旧进程否则端口会被占用。第二个vite 的局域网访问在 electron 开发场景中不太常用但如果遇到局域网打开空白的问题往往是 host 配置或代理设置导致的和 electron 本身关系不大。这些经验都是我一个个坑踩出来的分享出来就是希望后面走这条路的朋友能少走点弯路。这套组合本身很强大vue3 负责界面组织、ts 负责类型约束、elementPlus 提供现成组件、vite 带来开发效率、electron 把这一切装进桌面环境今天这套体系已经可以支撑起相当复杂的产品级应用。如果你打算自己搞一个桌面端效率工具、后台管理客户端或者音视频处理应用照着这个思路起步大概率能顺利走通。