1. 为什么是Vue3ElectronVite技术选型的底层逻辑先说结论这个组合是目前用Web技术做桌面端应用里开发体验和工程化上限都相当均衡的一套方案。我不太推荐新手一上来就选全家桶框架或者自研脚手架因为Electron的复杂度大头不在能不能跑起来而在怎么把主进程、渲染进程、预加载脚本这三块东西组织得清爽Vite的模块热替换能力加上Vue3的组合式API能把这种复杂度消化掉一大半。选型这事不能只看名气得回到实际开发场景里看问题。Electron内置了Chromium和Node.js本质上是一个浏览器服务器的合体运行时。你在页面上写的一切到最后都会跑在一个Chromium实例里而主进程那边则拥有完整的Node.js能力——文件读写、进程管理、系统托盘这些浏览器干不了的活交给它就对了。这时候你就会面临一个绕不开的问题渲染进程和主进程怎么通信有人习惯直接在渲染进程里开Node集成省事但安全风险直接拉满。更合理的做法是用预加载脚本开一个桥接通道用contextBridge暴露白名单API给页面这就是Electron官方文档里反复强调的安全基线。我们这套技术选型第一原则就是守住这条基线。Vite在这里扮演的角色容易被低估。它不只是快而是把主进程、预加载脚本、渲染进程这三类代码的构建边界一次性理清了。没有Vite的现代构建体系你可能要同时维护Webpack配置、Babel配置、TypeScript配置、Electron打包配置四个配置文件之间的版本兼容问题就能耗掉你两三天。Vite的插件机制和rollupOptions设计让我可以用一份配置文件管住三个不同构建目标的输出逻辑。Vue3就更不用多说了。桌面应用页面的复杂度一旦上去组件间的状态流转会很频繁。Vue3的组合式API配合reactive或第三方状态库在跨组件管理数据时比Options API要顺手得多。特别是做窗口间通信、系统主题监听这类逻辑时一个composables目录就能把这些全局状态收拢得明明白白。如果你是带着只想把网页套个壳的想法来的这套组合确实有点大材小用。但如果你后面计划做文件重命名工具、Markdown笔记、可视化图表桌面端、或者任何需要持续迭代的中大型桌面应用现在把工程地基打扎实是在省未来的心力。2. 环境准备与项目脚手架初始化第一步就决定成败写代码之前先把Node.js的版本问题处理干净。这个坑我在多台机器上踩过确实是第一步最容易出状况的地方。Electron的预编译二进制下载依赖Node.js的版本Vite 5以上也明确要求Node 18及以上才能跑。所以别犹豫直接装LTS版本的Node.js当前建议使用Node 20 LTS不要追新到奇数版本——那通常是实验版本跟Electron底层的兼容性容易出幺蛾子。确认版本的方式很简单node -v npm -v然后初始化项目目录。这里我先说一个跟Electron项目特有的关键习惯项目名不建议用中文也不建议含空格和特殊符号因为后续Electron的编译缓存目录和打包工具对路径非常敏感。曾经有位朋友的项目名里带了个空格结果莫名其妙地出现构建缓存找不到文件的问题排查了两个小时才定位到是路径解析的锅。mkdir vue3-electron-starter cd vue3-electron-starter npm init -y初始化完package.json之后我习惯第一时间把main字段改掉。Electron默认找main字段指向的文件作为主进程入口不指定的话会报Electron failed to install correctly或找不到入口的错误。接着安装核心依赖。这一步看起来简单但有一个版本组合的注意事项npm install electronlatest vuelatest npm install -D vitelatest vitejs/plugin-vue npm install -D electron-vite这里有个容易犯迷糊的地方electron-vite不是Vite官方出的而是专门为Electron项目做了一套开发时统一的构建方案它可以把主进程、预加载脚本、渲染进程三者的启动流整合到一个命令里。很多人第一反应是我自己配Vite Electron手动启动不是说不行只是手动配置意味着你要同时管理两个进程的启动顺序、端口占用、环境变量传递这些任务加起来的工作量远超你的直觉。我最开始也是手动配的后来切到electron-vite启动流程立刻变得干净很多。依赖装完后先别急着写代码。打开package.json把这些核心脚本补上{ name: vue3-electron-starter, version: 0.1.0, main: dist/main/index.js, scripts: { dev: electron-vite dev, build: electron-vite build, preview: electron-vite preview } }这里main指向dist/main/index.js是electron-vite的默认输出路径。如果你用的是纯ViteElectron手动方案那需要自己约定好输出目录并且每次打包前手动清理旧文件。再强调一次安装Electron时如果网络环境不理想二进制包下载超时会直接失败。这时候不是代码问题是网络问题。解决办法之一是设置Electron镜像源把~/.npmrc或项目根目录的.npmrc文件里加一行配置指向可用的镜像站。不过这个根据你实际的网络情况来定我不展开多说。一切装完先跑一个空项目验证流程。创建一个src/main/index.js文件作为主进程入口内容是最小可运行的Electron窗口代码。这里注意electron-vite默认会要求主进程和渲染进程在src下的特定目录结构里它按约定做事别自作主张改路径。3. 主进程、预加载脚本与渲染进程的分工先从一张目录图开始理解项目跑起来之前先建立全局认知。很多人上来就写代码写着写着就乱套根本原因是对Electron的三进程架构缺乏画面感。你可以把Electron应用想象成一个迷你公司主进程是行政前台负责接待系统级别的请求窗口创建、生命周期、文件读写它是唯一能直接接触Node.js API的角色。渲染进程是每个窗口里的业务部门负责画界面、响应用户操作但它运行在Chromium的沙盒环境里不能直接动用Node.js能力。预加载脚本是前台和业务部门之间的传话筒权限被严格限制只完成一件事——把主进程愿意开放的API安全地暴露给渲染进程。Vue3页面就是渲染进程里的业务部门它只关心展示什么和用户点什么不关心文件系统怎么写、Windows API怎么调。从目录设计看electron-vite约定了一套非常有辨识度的结构├── src │ ├── main # 主进程代码 │ │ └── index.js │ ├── preload # 预加载脚本 │ │ └── index.js │ └── renderer # 渲染进程Vue3应用 │ ├── index.html │ └── src │ ├── main.js │ └── App.vue这套约定的价值在于构建工具在打包时能清晰地知道哪种代码该走Electron主进程构建目标哪种代码该走浏览器兼容构建目标不需要你额外声明。为了让你更直观地感受三者的配合逻辑我给出一份最小但规范的主进程代码// src/main/index.js import { app, shell, BrowserWindow } from electron import { join } from path import { electronApp, optimizer, is } from electron-toolkit/utils function createWindow() { const mainWindow new BrowserWindow({ width: 1200, height: 800, show: false, autoHideMenuBar: true, webPreferences: { preload: join(__dirname, ../preload/index.js), sandbox: false, contextIsolation: true, nodeIntegration: false, webSecurity: true } }) mainWindow.on(ready-to-show, () { mainWindow.show() }) mainWindow.webContents.setWindowOpenHandler((details) { shell.openExternal(details.url) return { action: deny } }) if (is.dev process.env[ELECTRON_RENDERER_URL]) { mainWindow.loadURL(process.env[ELECTRON_RENDERER_URL]) } else { mainWindow.loadFile(join(__dirname, ../renderer/index.html)) } } app.whenReady().then(() { electronApp.setAppUserModelId(com.example.app) createWindow() app.on(activate, function () { if (BrowserWindow.getAllWindows().length 0) createWindow() }) }) app.on(window-all-closed, () { if (process.platform ! darwin) { app.quit() } })这里有两个容易出问题的细节值得展开说。第一contextIsolation: true和nodeIntegration: false这组配置是安全红线。既然用了Vue3做渲染层你的页面就应该把自己当成一个纯浏览器环境来开发不要指望页面里能直接require(fs)。所有Node.js操作全部走预加载脚本暴露的API。第二is.dev process.env[ELECTRON_RENDERER_URL]这一行是开发与生产环境切换的关键。electron-vite在开发模式启动时会先启动Vite的Dev Server然后把地址写进环境变量。主进程检测到这个变量就去加载远程开发页面支持热更新生产打包后这个变量不存在就加载构建出来的静态HTML文件。这一套逻辑如果你手动实现要多写不少桥接代码而electron-vite直接帮你处理好了。接下来是预加载脚本这段代码决定了渲染进程的可用能力边界// src/preload/index.js import { contextBridge, ipcRenderer } from electron const api { getAppVersion: () ipcRenderer.invoke(app:get-version), openExternal: (url) ipcRenderer.invoke(shell:open-external, url) } contextBridge.exposeInMainWorld(api, api)再看主进程里对应的IPC处理逻辑需要写到ipcMain模块里// src/main/index.js import { ipcMain } from electron ipcMain.handle(app:get-version, () app.getVersion()) ipcMain.handle(shell:open-external, (_event, url) shell.openExternal(url))渲染进程里直接这样调用// src/renderer/src/App.vue script setup const version await window.api.getAppVersion() console.log(当前应用版本, version) /script这套链路走通了你就掌握Electron应用的最小通信范式。4. 让页面先跑起来Vite开发服务器的接入与踩坑记录很多教程到上一节就停了但真实开发中你会发现页面热更新怎么不生效跨域请求为什么报错控制台为什么一堆奇怪的警告这一节我专门梳理开发调试阶段的操作顺序和常见问题。首先理解一下开发模式下的请求链路。electron-vite dev命令做了一件非常巧妙的编排先启动Vite Dev Server默认地址通常是http://localhost:5173然后启动Electron主进程主进程再从环境变量ELECTRON_RENDERER_URL里拿到这个地址直接加载它。这意味着你的Vue3页面在开发时本质上是跑在一个浏览器样的环境里前端代码的改动会触发Vite的模块热替换页面样式和组件状态几乎秒级更新不需要手动关掉窗口重启应用。我第一次跑通这套流程时对比此前用纯Electron每次改代码都要手动重启项目的体验确实是质的变化。但有几个细节不处理这个流程并不顺畅。问题一Vite开发服务器端口被占用。如果你的机器上同时开着多个项目5173端口很容易被别的Vite实例占住。这时候electron-vite会自动往上找可用端口但这可能导致你浏览器里手动开的旧页面地址不再匹配。解决方式是显式指定端口在项目根目录创建electron.vite.config.js// electron.vite.config.js import { defineConfig } from electron-vite import vue from vitejs/plugin-vue export default defineConfig({ main: {}, preload: {}, renderer: { plugins: [vue()], server: { port: 5173, strictPort: true } } })问题二渲染进程里引用Node.js模块直接报错。这个报错信息具有极大迷惑性——看起来好像是没安装依赖但实际上是你违反了进程边界。由于我们设置了nodeIntegration: false渲染进程的代码执行环境是浏览器沙盒module、require、process这些Node.js全局变量根本不存在。每当你觉得这个功能在Node里很顺手就在页面里用一下基本都会遇到这个错误。正确的做法永远是把逻辑下沉到主进程或预加载脚本然后通过IPC调用。问题三页面里调用HTTP请求遇到跨域限制。Electron里的渲染进程仍遵守浏览器的同源策略。如果开发时你的前端访问https://api.example.com而后端接口没有配置Access-Control-Allow-Origin请求会被浏览器拦下。开发阶段最省事的解决办法是在electron.vite.config.js里配置Vite的server.proxy把代理转发逻辑交给Dev Server处理renderer: { server: { proxy: { /api: { target: https://api.example.com, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) } } } }我在一个失败的经验里学到这个方案当时做某央社内容聚合Demo后端同事没空配跨域我在自己代码里加了一堆Access-Control-Allow-Origin响应头也没解决最后是代理方案救了场。页面里把请求路径写成/api/xxx代理自动转发到目标服务器跨域限制彻底绕开了。问题四主进程代码修改后不会自动重启。Vite的热更新只管渲染进程Electron主进程和预加载脚本的变动默认需要手动触发重启。好在electron-vite在开发模式下配置了主进程构建的watch模式——检测到主进程文件变化会自动重启Electron应用。实测下来很稳但我还是建议养成手动确认的习惯每次改完主进程代码留意终端面板的输出日志看它是否真的完成了重启。5. 生产构建与打包配置不只是把代码压一行开发模式跑通只是热身真正体现工程化水平的是打包环节。Electron打包的难点不只是编译还涉及三个不同目标的产物整理、应用图标、安装包格式、代码签名每一环都是独立的知识域。这一节聚焦第一期最实用的构建方案。先用一张表理清楚electron-vite build的输出逻辑构建目标输入目录输出目录产物格式主进程src/maindist/mainCommonJS格式index.js预加载src/preloaddist/preloadCommonJS格式index.js渲染进程src/rendererdist/renderer静态HTML/CSS/JS资源三个目标在一条命令里按依赖顺序完成构建产出到同一个dist目录。主进程代码里用它拼窗口加载路径时才不会出错——这也是main字段要指向dist/main/index.js的原因。接下来是安装包生成。我用的打包配套是electron-builder它跟electron-vite配合相当顺畅npm install -D electron-builder然后给package.json增加一个build配置区{ build: { appId: com.example.yourapp, productName: YourAppName, directories: { output: release }, files: [ dist/**/*, package.json ], win: { target: nsis }, mac: { target: dmg }, linux: { target: AppImage } } }然后增加打包脚本{ scripts: { build:win: electron-vite build electron-builder --win, build:mac: electron-vite build electron-builder --mac, build:linux: electron-vite build electron-builder --linux } }执行npm run build:win在Windows机器上你会得到一个NSIS安装包在release目录里。如果没报错说明整个项目从开发到生产的分发生命周期彻底打通了。打包过程中我遇到最奇妙的坑是appId冲突。某次我为模拟项目X打包时appId跟一个线上应用撞了安装后竟然复用了对方的应用目录导致出现诡异的配置文件残留。此后我的建议是appId一定要用你真正拥有的域名倒过来写不要用com.electron.template这种默认值也不要用com.example这种保底值。生产构建还有一个很容易被忽略的控制台安全警告打包出的应用在加载本地HTML时如果有CSP缺失Electron会在开发者工具里打出警告。虽然不影响运行但作为一个负责任的工程我会在src/renderer/index.html里加上基础内容安全策略meta http-equivContent-Security-Policy contentdefault-src self; script-src self; style-src self unsafe-inline; img-src self data: /加CSP还有一个好处能拦截绝大多数的远程脚本注入类风险。桌面上分发的应用会被用户信任安全基线定得多高都不为过。6. 第一期工程的目录规范与常见看起来正常但迟早出事的写法项目搭建完毕最后我想专门聊一个不体现在功能里、但决定你后续迭代效率的点目录和代码的组织纪律。一些写法当时看确实能跑但一个月后回看就是一地鸡毛。须避免的写法一渲染进程里操作文件系统。不管是通过任何间接手段达成——把Node模块打包进页面、用process全局变量手动开启集成——都是在给自己埋雷。安全不提单说调试体验主进程的崩溃日志和渲染进程的报错信息隔着两个世界排查问题时你会多花好几倍时间。须避免的写法二预加载脚本里写大量业务代码。预加载脚本的职责是桥接不是一个藏业务逻辑的地方。如果你发现预加载脚本里出现了上千行代码一定是架构设计出了问题。举个例子预加载脚本里做文件列表的解析、数据库的初始化这些都是典型的主进程职责或独立模块职责硬塞进桥接层会让安全边界彻底失效。须避免的写法三主进程代码全部堆在一个文件里。第一期项目规模不大把窗口创建、IPC处理、应用生命周期放在一个文件里勉强能看。但一旦新增窗口类型多起来单文件就会变得寸步难行。我的实践是尽早引入模块化拆分src/main ├── index.js # 入口仅做应用初始化 ├── windows # 窗口创建与窗口状态管理 │ └── mainWindow.js ├── ipc # IPC处理器按业务域拆分 │ ├── appHandlers.js │ └── shellHandlers.js └── utils # 通用工具函数这个拆分的核心思想是模块之间的依赖方向要单向流动不该出现窗口模块调用工具模块、工具模块又反过来依赖窗口模块的循环引用。期末自查清单每次我认为某期项目搭建完成时都会按这份清单逐项过一遍package.json中的main字段指向正确且输出路径存在吗contextIsolation和nodeIntegration配置是否符合安全基线主进程里所有ipcMain.handle有没有对应的ipcRenderer.invoke调用方开发模式和生产模式的加载路径切换逻辑有没有被破坏打包出来的安装包是否在目标机器的干净环境中跑通是否准备好了应用图标至少准备256x256的PNG第一期要交付的核心能力就是这些一套能启动、能热更新、能通信、能构建的全链路项目脚手架。有了这块地基后续的功能开发、性能优化、多窗口管理、自动更新才有下脚的地方。第二期我会讲如何把窗口管理抽成独立模块以及如何在渲染层安全地封装主进程能力让页面代码始终保持纯浏览器环境的认知上期这套基线的价值会在多窗口场景里体现得更加明显。 1. 为什么是Vue3ElectronVite技术选型的底层逻辑先说结论这个组合是目前用Web技术做桌面端应用里开发体验和工程化上限都相当均衡的一套方案。我不太推荐新手一上来就选全家桶框架或者自研脚手架因为Electron的复杂度大头不在能不能跑起来而在怎么把主进程、渲染进程、预加载脚本这三块东西组织得清爽Vite的模块热替换能力加上Vue3的组合式API能把这种复杂度消化掉一大半。选型这事不能只看名气得回到实际开发场景里看问题。Electron内置了Chromium和Node.js本质上是一个浏览器服务器的合体运行时。你在页面上写的一切到最后都会跑在一个Chromium实例里而主进程那边则拥有完整的Node.js能力——文件读写、进程管理、系统托盘这些浏览器干不了的活交给它就对了。这时候你就会面临一个绕不开的问题渲染进程和主进程怎么通信有人习惯直接在渲染进程里开Node集成省事但安全风险直接拉满。更合理的做法是用预加载脚本开一个桥接通道用contextBridge暴露白名单API给页面这就是Electron官方文档里反复强调的安全基线。我们这套技术选型第一原则就是守住这条基线。Vite在这里扮演的角色容易被低估。它不只是快而是把主进程、预加载脚本、渲染进程这三类代码的构建边界一次性理清了。没有Vite的现代构建体系你可能要同时维护Webpack配置、Babel配置、TypeScript配置、Electron打包配置四个配置文件之间的版本兼容问题就能耗掉你两三天。Vite的插件机制和rollupOptions设计让我可以用一份配置文件管住三个不同构建目标的输出逻辑。Vue3就更不用多说了。桌面应用页面的复杂度一旦上去组件间的状态流转会很频繁。Vue3的组合式API配合reactive或第三方状态库在跨组件管理数据时比Options API要顺手得多。特别是做窗口间通信、系统主题监听这类逻辑时一个composables目录就能把这些全局状态收拢得明明白白。如果你是带着只想把网页套个壳的想法来的这套组合确实有点大材小用。但如果你后面计划做文件重命名工具、Markdown笔记、可视化图表桌面端、或者任何需要持续迭代的中大型桌面应用现在把工程地基打扎实是在省未来的心力。2. 环境准备与项目脚手架初始化第一步就决定成败写代码之前先把Node.js的版本问题处理干净。这个坑我在多台机器上踩过确实是第一步最容易出状况的地方。Electron的预编译二进制下载依赖Node.js的版本Vite 5以上也明确要求Node 18及以上才能跑。所以别犹豫直接装LTS版本的Node.js当前建议使用Node 20 LTS不要追新到奇数版本——那通常是实验版本跟Electron底层的兼容性容易出幺蛾子。确认版本的方式很简单node -v npm -v然后初始化项目目录。这里我先说一个跟Electron项目特有的关键习惯项目名不建议用中文也不建议含空格和特殊符号因为后续Electron的编译缓存目录和打包工具对路径非常敏感。曾经有位朋友的项目名里带了个空格结果莫名其妙地出现构建缓存找不到文件的问题排查了两个小时才定位到是路径解析的锅。mkdir vue3-electron-starter cd vue3-electron-starter npm init -y初始化完package.json之后我习惯第一时间把main字段改掉。Electron默认找main字段指向的文件作为主进程入口不指定的话会报Electron failed to install correctly或找不到入口的错误。接着安装核心依赖。这一步看起来简单但有一个版本组合的注意事项npm install electronlatest vuelatest npm install -D vitelatest vitejs/plugin-vue npm install -D electron-vite这里有个容易犯迷糊的地方electron-vite不是Vite官方出的而是专门为Electron项目做了一套开发时统一的构建方案它可以把主进程、预加载脚本、渲染进程三者的启动流整合到一个命令里。很多人第一反应是我自己配Vite Electron手动启动不是说不行只是手动配置意味着你要同时管理两个进程的启动顺序、端口占用、环境变量传递这些任务加起来的工作量远超你的直觉。我最开始也是手动配的后来切到electron-vite启动流程立刻变得干净很多。依赖装完后先别急着写代码。打开package.json把这些核心脚本补上{ name: vue3-electron-starter, version: 0.1.0, main: dist/main/index.js, scripts: { dev: electron-vite dev, build: electron-vite build, preview: electron-vite preview } }这里main指向dist/main/index.js是electron-vite的默认输出路径。如果你用的是纯ViteElectron手动方案那需要自己约定好输出目录并且每次打包前手动清理旧文件。再强调一次安装Electron时如果网络环境不理想二进制包下载超时会直接失败。这时候不是代码问题是网络问题。解决办法之一是设置Electron镜像源把~/.npmrc或项目根目录的.npmrc文件里加一行配置指向可用的镜像站。不过这个根据你实际的网络情况来定我不展开多说。一切装完先跑一个空项目验证流程。创建一个src/main/index.js文件作为主进程入口内容是最小可运行的Electron窗口代码。这里注意electron-vite默认会要求主进程和渲染进程在src下的特定目录结构里它按约定做事别自作主张改路径。3. 主进程、预加载脚本与渲染进程的分工先从一张目录图开始理解项目跑起来之前先建立全局认知。很多人上来就写代码写着写着就乱套根本原因是对Electron的三进程架构缺乏画面感。你可以把Electron应用想象成一个迷你公司主进程是行政前台负责接待系统级别的请求窗口创建、生命周期、文件读写它是唯一能直接接触Node.js API的角色。渲染进程是每个窗口里的业务部门负责画界面、响应用户操作但它运行在Chromium的沙盒环境里不能直接动用Node.js能力。预加载脚本是前台和业务部门之间的传话筒权限被严格限制只完成一件事——把主进程愿意开放的API安全地暴露给渲染进程。Vue3页面就是渲染进程里的业务部门它只关心展示什么和用户点什么不关心文件系统怎么写、Windows API怎么调。从目录设计看electron-vite约定了一套非常有辨识度的结构├── src │ ├── main # 主进程代码 │ │ └── index.js │ ├── preload # 预加载脚本 │ │ └── index.js │ └── renderer # 渲染进程Vue3应用 │ ├── index.html │ └── src │ ├── main.js │ └── App.vue这套约定的价值在于构建工具在打包时能清晰地知道哪种代码该走Electron主进程构建目标哪种代码该走浏览器兼容构建目标不需要你额外声明。为了让你更直观地感受三者的配合逻辑我给出一份最小但规范的主进程代码// src/main/index.js import { app, shell, BrowserWindow } from electron import { join } from path import { electronApp, optimizer, is } from electron-toolkit/utils function createWindow() { const mainWindow new BrowserWindow({ width: 1200, height: 800, show: false, autoHideMenuBar: true, webPreferences: { preload: join(__dirname, ../preload/index.js), sandbox: false, contextIsolation: true, nodeIntegration: false, webSecurity: true } }) mainWindow.on(ready-to-show, () { mainWindow.show() }) mainWindow.webContents.setWindowOpenHandler((details) { shell.openExternal(details.url) return { action: deny } }) if (is.dev process.env[ELECTRON_RENDERER_URL]) { mainWindow.loadURL(process.env[ELECTRON_RENDERER_URL]) } else { mainWindow.loadFile(join(__dirname, ../renderer/index.html)) } } app.whenReady().then(() { electronApp.setAppUserModelId(com.example.app) createWindow() app.on(activate, function () { if (BrowserWindow.getAllWindows().length 0) createWindow() }) }) app.on(window-all-closed, () { if (process.platform ! darwin) { app.quit() } })这里有两个容易出问题的细节值得展开说。第一contextIsolation: true和nodeIntegration: false这组配置是安全红线。既然用了Vue3做渲染层你的页面就应该把自己当成一个纯浏览器环境来开发不要指望页面里能直接require(fs)。所有Node.js操作全部走预加载脚本暴露的API。第二is.dev process.env[ELECTRON_RENDERER_URL]这一行是开发与生产环境切换的关键。electron-vite在开发模式启动时会先启动Vite的Dev Server然后把地址写进环境变量。主进程检测到这个变量就去加载远程开发页面支持热更新生产打包后这个变量不存在就加载构建出来的静态HTML文件。这一套逻辑如果你手动实现要多写不少桥接代码而electron-vite直接帮你处理好了。接下来是预加载脚本这段代码决定了渲染进程的可用能力边界// src/preload/index.js import { contextBridge, ipcRenderer } from electron const api { getAppVersion: () ipcRenderer.invoke(app:get-version), openExternal: (url) ipcRenderer.invoke(shell:open-external, url) } contextBridge.exposeInMainWorld(api, api)再看主进程里对应的IPC处理逻辑需要写到ipcMain模块里// src/main/index.js import { ipcMain } from electron ipcMain.handle(app:get-version, () app.getVersion()) ipcMain.handle(shell:open-external, (_event, url) shell.openExternal(url))渲染进程里直接这样调用// src/renderer/src/App.vue script setup const version await window.api.getAppVersion() console.log(当前应用版本, version) /script这套链路走通了你就掌握Electron应用的最小通信范式。4. 让页面先跑起来Vite开发服务器的接入与踩坑记录很多教程到上一节就停了但真实开发中你会发现页面热更新怎么不生效跨域请求为什么报错控制台为什么一堆奇怪的警告这一节我专门梳理开发调试阶段的操作顺序和常见问题。首先理解一下开发模式下的请求链路。electron-vite dev命令做了一件非常巧妙的编排先启动Vite Dev Server默认地址通常是http://localhost:5173然后启动Electron主进程主进程再从环境变量ELECTRON_RENDERER_URL里拿到这个地址直接加载它。这意味着你的Vue3页面在开发时本质上是跑在一个浏览器样的环境里前端代码的改动会触发Vite的模块热替换页面样式和组件状态几乎秒级更新不需要手动关掉窗口重启应用。我第一次跑通这套流程时对比此前用纯Electron每次改代码都要手动重启项目的体验确实是质的变化。但有几个细节不处理这个流程并不顺畅。问题一Vite开发服务器端口被占用。如果你的机器上同时开着多个项目5173端口很容易被别的Vite实例占住。这时候electron-vite会自动往上找可用端口但这可能导致你浏览器里手动开的旧页面地址不再匹配。解决方式是显式指定端口在项目根目录创建electron.vite.config.js// electron.vite.config.js import { defineConfig } from electron-vite import vue from vitejs/plugin-vue export default defineConfig({ main: {}, preload: {}, renderer: { plugins: [vue()], server: { port: 5173, strictPort: true } } })问题二渲染进程里引用Node.js模块直接报错。这个报错信息具有极大迷惑性——看起来好像是没安装依赖但实际上是你违反了进程边界。由于我们设置了nodeIntegration: false渲染进程的代码执行环境是浏览器沙盒module、require、process这些Node.js全局变量根本不存在。每当你觉得这个功能在Node里很顺手就在页面里用一下基本都会遇到这个错误。正确的做法永远是把逻辑下沉到主进程或预加载脚本然后通过IPC调用。问题三页面里调用HTTP请求遇到跨域限制。Electron里的渲染进程仍遵守浏览器的同源策略。如果开发时你的前端访问https://api.example.com而后端接口没有配置Access-Control-Allow-Origin请求会被浏览器拦下。开发阶段最省事的解决办法是在electron.vite.config.js里配置Vite的server.proxy把代理转发逻辑交给Dev Server处理renderer: { server: { proxy: { /api: { target: https://api.example.com, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) } } } }我在一个失败的经验里学到这个方案当时做某央社内容聚合Demo后端同事没空配跨域我在自己代码里加了一堆Access-Control-Allow-Origin响应头也没解决最后是代理方案救了场。页面里把请求路径写成/api/xxx代理自动转发到目标服务器跨域限制彻底绕开了。问题四主进程代码修改后不会自动重启。Vite的热更新只管渲染进程Electron主进程和预加载脚本的变动默认需要手动触发重启。好在electron-vite在开发模式下配置了主进程构建的watch模式——检测到主进程文件变化会自动重启Electron应用。实测下来很稳但我还是建议养成手动确认的习惯每次改完主进程代码留意终端面板的输出日志看它是否真的完成了重启。5. 生产构建与打包配置不只是把代码压一行开发模式跑通只是热身真正体现工程化水平的是打包环节。Electron打包的难点不只是编译还涉及三个不同目标的产物整理、应用图标、安装包格式、代码签名每一环都是独立的知识域。这一节聚焦第一期最实用的构建方案。先用一张表理清楚electron-vite build的输出逻辑构建目标输入目录输出目录产物格式主进程src/maindist/mainCommonJS格式index.js预加载src/preloaddist/preloadCommonJS格式index.js渲染进程src/rendererdist/renderer静态HTML/CSS/JS资源三个目标在一条命令里按依赖顺序完成构建产出到同一个dist目录。主进程代码里用它拼窗口加载路径时才不会出错——这也是main字段要指向dist/main/index.js的原因。接下来是安装包生成。我用的打包配套是electron-builder它跟electron-vite配合相当顺畅npm install -D electron-builder然后给package.json增加一个build配置区{ build: { appId: com.example.yourapp, productName: YourAppName, directories: { output: release }, files: [ dist/**/*, package.json ], win: { target: nsis }, mac: { target: dmg }, linux: { target: AppImage } } }然后增加打包脚本{ scripts: { build:win: electron-vite build electron-builder --win, build:mac: electron-vite build electron-builder --mac, build:linux: electron-vite build electron-builder --linux } }执行npm run build:win在Windows机器上你会得到一个NSIS安装包在release目录里。如果没报错说明整个项目从开发到生产的分发生命周期彻底打通了。打包过程中我遇到最奇妙的坑是appId冲突。某次我为模拟项目X打包时appId跟一个线上应用撞了安装后竟然复用了对方的应用目录导致出现诡异的配置文件残留。此后我的建议是appId一定要用你真正拥有的域名倒过来写不要用com.electron.template这种默认值也不要用com.example这种保底值。生产构建还有一个很容易被忽略的控制台安全警告打包出的应用在加载本地HTML时如果有CSP缺失Electron会在开发者工具里打出警告。虽然不影响运行但作为一个负责任的工程我会在src/renderer/index.html里加上基础内容安全策略meta http-equivContent-Security-Policy contentdefault-src self; script-src self; style-src self unsafe-inline; img-src self data: /加CSP还有一个好处能拦截绝大多数的远程脚本注入类风险。桌面上分发的应用会被用户信任安全基线定得多高都不为过。6. 第一期工程的目录规范与常见看起来正常但迟早出事的写法项目搭建完毕最后我想专门聊一个不体现在功能里、但决定你后续迭代效率的点目录和代码的组织纪律。一些写法当时看确实能跑但一个月后回看就是一地鸡毛。须避免的写法一渲染进程里操作文件系统。不管是通过任何间接手段达成——把Node模块打包进页面、用process全局变量手动开启集成——都是在给自己埋雷。安全不提单说调试体验主进程的崩溃日志和渲染进程的报错信息隔着两个世界排查问题时你会多花好几倍时间。须避免的写法二预加载脚本里写大量业务代码。预加载脚本的职责是桥接不是一个藏业务逻辑的地方。如果你发现预加载脚本里出现了上千行代码一定是架构设计出了问题。举个例子预加载脚本里做文件列表的解析、数据库的初始化这些都是典型的主进程职责或独立模块职责硬塞进桥接层会让安全边界彻底失效。须避免的写法三主进程代码全部堆在一个文件里。第一期项目规模不大把窗口创建、IPC处理、应用生命周期放在一个文件里勉强能看。但一旦新增窗口类型多起来单文件就会变得寸步难行。我的实践是尽早引入模块化拆分src/main ├── index.js # 入口仅做应用初始化 ├── windows # 窗口创建与窗口状态管理 │ └── mainWindow.js ├── ipc # IPC处理器按业务域拆分 │ ├── appHandlers.js │ └── shellHandlers.js └── utils # 通用工具函数这个拆分的核心思想是模块之间的依赖方向要单向流动不该出现窗口模块调用工具模块、工具模块又反过来依赖窗口模块的循环引用。期末自查清单每次我认为某期项目搭建完成时都会按这份清单逐项过一遍package.json中的main字段指向正确且输出路径存在吗contextIsolation和nodeIntegration配置是否符合安全基线主进程里所有ipcMain.handle有没有对应的ipcRenderer.invoke调用方开发模式和生产模式的加载路径切换逻辑有没有被破坏打包出来的安装包是否在目标机器的干净环境中跑通是否准备好了应用图标至少准备256x256的PNG第一期要交付的核心能力就是这些一套能启动、能热更新、能通信、能构建的全链路项目脚手架。有了这块地基后续的功能开发、性能优化、多窗口管理、自动更新才有下脚的地方。第二期我会讲如何把窗口管理抽成独立模块以及如何在渲染层安全地封装主进程能力让页面代码始终保持纯浏览器环境的认知上期这套基线的价值会在多窗口场景里体现得更加明显。