与 Vue / React / 原生 JS 项目的整合方式

Electron 的渲染进程本质上就是一个 Chromium 浏览器窗口，所以它几乎可以运行任何现代前端工程。一个最常见的疑问是：“我是不是需要从头学一套特殊的项目结构才能把 Electron 塞进我的 Vue/React 项目里？” 答案是否定的——你完全可以在保留原有前端构建体系的前提下，将 Electron 作为一个“启动壳”集成进去，整个过程比想象中简单很多。

原生 JavaScript 项目：最小化入门

如果你只是想快速验证一个想法，或者项目本身并不依赖任何前端框架，直接使用原生 HTML/CSS/JS 是最直接的方案。

项目结构示例

my-electron-app/
├── package.json
├── main.js          # Electron 主进程
├── preload.js       # 预加载脚本（安全桥接）
├── index.html       # 主窗口页面
├── renderer.js      # 渲染进程脚本
└── style.css

整合步骤

初始化 package.json 并安装 Electron 作为开发依赖：

   npm init -y
   npm install --save-dev electron

编写 main.js，创建一个窗口并加载 index.html：

   const { app, BrowserWindow } = require('electron');
   const path = require('path');

   function createWindow() {
     const win = new BrowserWindow({
       width: 800,
       height: 600,
       webPreferences: {
         preload: path.join(__dirname, 'preload.js'),
       },
     });
     win.loadFile('index.html');
   }

   app.whenReady().then(createWindow);

在 index.html 中像正常网页一样引入 renderer.js 和 style.css。
启动应用：npx electron .。

这种模式非常适合学习、原型开发或小型工具。但随着界面变复杂，手动管理 DOM 和状态会变得吃力，这时就需要引入前端框架了。

整合 Vue 项目

将 Electron 整合进 Vue 项目有两种主流方式：使用社区模板（如 electron-vite）或手动改造现有 Vue CLI/Vite 项目。这里推荐使用 Vite 插件 vite-plugin-electron，因为它对现有项目侵入最小，且完美支持热更新。

步骤（以 Vue 3 + Vite 为例）

创建一个常规的 Vue 项目（假设已存在，或通过 npm create vue@latest 生成）。
安装依赖：

   npm install --save-dev electron vite-plugin-electron electron-builder

在 vite.config.ts 中配置插件：

   import { defineConfig } from 'vite'
   import vue from '@vitejs/plugin-vue'
   import electron from 'vite-plugin-electron'

   export default defineConfig({
     plugins: [
       vue(),
       electron([
         {
           entry: 'electron/main.js', // 主进程入口
         },
         {
           entry: 'electron/preload.js', // 预加载脚本
           onstart(options) {
             options.reload(); // 预加载脚本变更时刷新窗口
           },
         },
       ]),
     ],
   })

创建 electron/main.js 文件，内容与原生方式一致，但窗口加载地址改为开发环境的 URL（由 Vite 提供）：

   const { app, BrowserWindow } = require('electron');
   const path = require('path');

   function createWindow() {
     const win = new BrowserWindow({
       webPreferences: {
         preload: path.join(__dirname, 'preload.js'),
       },
     });
     // 开发环境加载 Vite 的 dev server，生产环境加载打包后的文件
     if (process.env.VITE_DEV_SERVER_URL) {
       win.loadURL(process.env.VITE_DEV_SERVER_URL);
     } else {
       win.loadFile(path.join(__dirname, '../dist/index.html'));
     }
   }

   app.whenReady().then(createWindow);

在 package.json 中添加启动脚本：

   "scripts": {
     "dev": "vite",
     "build": "vite build",
     "electron:dev": "vite",
     "electron:build": "vite build && electron-builder"
   }

运行 npm run electron:dev 即可启动带热更新的 Electron 开发环境。

在这种模式下，Vue 的开发体验完全保留：组件热更新、TypeScript 支持、单文件组件 (SFC) 都能正常使用。而 Electron 的主进程代码有任何修改，vite-plugin-electron 也会自动重启应用，整个开发循环非常顺畅。

整合 React 项目

React 项目的整合思路与 Vue 几乎一致。你同样可以选择 Vite + vite-plugin-electron，或者使用 Create React App 配合 electron。下面以 Vite + React 为例说明。

步骤

通过 Vite 创建 React 项目（npm create vite@latest my-react-app -- --template react）。
安装依赖：

   npm install --save-dev electron vite-plugin-electron

在 vite.config.js 中配置插件（写法与 Vue 相同，注意调整入口文件路径）。
创建 electron/main.js 和 electron/preload.js，内容与 Vue 示例相同。
启动开发：npm run dev 会同时启动 Vite 和 Electron，React 组件的热更新即时生效。

对于使用 Create React App 的项目，也可以选择安装 electron 并增加一个单独的启动脚本，但这种方式需要自行处理开发时的端口同步和打包流程，不如 Vite 插件方案来得优雅。因此，对于新项目强烈建议直接采用 Vite 为基础构建管线。

两种整合模式的对比与选择

| 整合模式 | 优点 | 缺点 |
|---------|------|-----|
| 侵入式框架模板（如 electron-forge with webpack/vite） | 开箱即用，配置少，适合新手 | 强绑定，后期自定义构建流程可能受限 |
| 插件注入式（如 vite-plugin-electron） | 对前端项目零侵入，保留原有开发和构建体验 | 需要手动创建主进程文件，对 Electron 基础有一定了解 |

对于大多数有现成前端项目的团队，插件注入式是最自然的选择——你完全不用改变原有项目结构，只需要新增一个 electron 文件夹存放主进程相关代码，然后通过插件将 Electron 注入到开发流程中。

调用系统能力的最佳实践

无论你选择哪种整合方式，有一点是共通的：渲染进程（Vue/React/原生 JS）不应该直接访问 Node.js 或 Electron 的原生 API。这既是安全考量，也是为了让你的前端代码保持纯净，方便未来复用到纯 Web 端。

正确的做法是：通过预加载脚本（preload.js）使用 contextBridge 暴露一组经过筛选的安全 API，例如：

// preload.js
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('electronAPI', {
  openFileDialog: () => ipcRenderer.invoke('dialog:openFile'),
  saveFile: (data) => ipcRenderer.invoke('file:save', data),
  getAppVersion: () => ipcRenderer.invoke('app:version'),
});

然后在你的 Vue 组件或 React 函数组件中，直接通过 window.electronAPI.openFileDialog() 调用这些能力。主进程通过 ipcMain.handle 响应这些事件，从而在完全隔离的情况下完成任务。这种模式让前端代码与 Electron 环境解耦，即使将来需要将应用迁移到 Web 或 Tauri 等其他平台，前端部分也几乎不需要改动。

总结一下：Electron 与现有前端项目的整合并不是什么高深的魔法。无论你用的是最朴素的原生 JavaScript，还是工程化程度极高的 Vue/React，只需要理解“Electron 就是给前端项目套上一个可调用系统 API 的浏览器壳”这一核心思想，就能找到最适合你的整合路径。选择一种低侵入性的插件方案，写好主进程和预加载脚本，你的前端应用就能无缝进化为一个功能完备的桌面软件。