以下是从 0 开始搭建 Vite + Electron 项目 到 完成多平台打包 的完整步骤，确保每一步可执行且兼容 macOS/Windows/Linux：
一、环境准备
1. 安装 Node.js
- 推荐使用 LTS 版本（如 v20.x），确保 npm 可用：下载地址：Node.js 官网验证安装：
node -v # 输出 v20.x.x npm -v # 输出对应版本
2. 安装依赖加速工具（可选，国内网络推荐）
# 配置 npm 镜像（加速依赖下载）
npm config set registry https://registry.npmmirror.com/ # 配置 Electron 镜像（解决二进制文件下载慢的问题）
npm config set electron_mirror https://npmmirror.com/mirrors/electron/
二、创建项目
1. 初始化项目文件夹
# 创建项目目录并进入
mkdir electron-vite-app && cd electron-vite-app
# 初始化 npm 项目（一路回车默认配置）
npm init -y
2. 安装核心依赖
# 安装开发依赖（Vite + Electron 相关工具）
npm install vite vite-plugin-electron electron electron-builder --save-dev
三、配置核心文件
1. 创建 Vite 配置文件（vite.config.js）
import { defineConfig } from 'vite'; import electron from 'vite-plugin-electron'; export default defineConfig({ plugins: [ electron({ entry: 'main.js', // 指定 Electron 主进程入口 }), ], server: { port: 3000, // 开发服务器端口（默认） }, build: { outDir: 'dist', // 前端资源打包目录 }, });
2. 创建 Electron 主进程（main.js）
const { app, BrowserWindow, ipcMain } = require('electron'); const path = require('path'); // 判断开发环境（Vite 自动注入环境变量） const isDev = !!process.env.VITE_DEV_SERVER_URL; let mainWindow; // 创建窗口 function createWindow() { mainWindow = new BrowserWindow({ width: 1024, height: 768, webPreferences: { nodeIntegration: false, // 禁用 Node 集成（安全） contextIsolation: true, // 启用上下文隔离（安全） preload: path.join(__dirname, 'preload.js'), // 预加载脚本 devTools: isDev, // 开发环境启用调试工具 }, }); // 加载页面：开发环境用 Vite 服务器，生产环境用本地文件 if (isDev) { mainWindow.loadURL(process.env.VITE_DEV_SERVER_URL); mainWindow.webContents.openDevTools(); // 自动打开调试工具 } else { mainWindow.loadFile(path.join(__dirname, '../dist/index.html')); } // 窗口关闭时清理 mainWindow.on('closed', () => { mainWindow = null; }); } // 主进程与渲染进程通信示例 ipcMain.handle('get-platform', () => process.platform); // 返回当前系统平台 ipcMain.on('log', (_, msg) => console.log('渲染进程日志：', msg)); // 接收日志 // 应用就绪后创建窗口 app.whenReady().then(createWindow); // 适配 macOS：应用激活时重建窗口 app.on('activate', () => { if (BrowserWindow.getAllWindows().length === 0) createWindow(); }); // 所有窗口关闭时退出（macOS 除外） app.on('window-all-closed', () => { if (process.platform !== 'darwin') app.quit(); });
3. 创建预加载脚本（preload.js，进程通信桥梁）
运行
const { contextBridge, ipcRenderer } = require('electron'); // 向渲染进程暴露安全 API（禁止直接暴露 ipcRenderer） contextBridge.exposeInMainWorld('electronAPI', { getPlatform: () => ipcRenderer.invoke('get-platform'), // 调用主进程方法 sendLog: (msg) => ipcRenderer.send('log', msg), // 发送消息到主进程 });
4. 创建渲染进程页面（index.html）
预览
<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>Electron + Vite 应用</title> </head> <body> <h1>Hello Electron + Vite!</h1> <p>当前系统：<span id="platform"></span></p> <button onclick="sendLog()">发送日志到主进程</button> <script> // 调用预加载脚本暴露的 API window.electronAPI.getPlatform().then(platform => { document.getElementById('platform').textContent = platform; }); function sendLog() { window.electronAPI.sendLog('这是一条来自渲染进程的日志'); } </script> </body> </html>
5. 配置 package.json（关键脚本和打包配置）
{ "name": "electron-vite-app", "version": "1.0.0", "main": "main.js", "scripts": { "dev": "vite", // 启动开发环境（热重载） "build": "vite build && electron-builder" // 打包生产版本 }, "build": { "appId": "com.example.electronvite", // 应用唯一标识（反向域名格式） "productName": "ElectronViteApp", // 应用名称 "directories": { "output": "release" // 打包输出目录 }, "mac": { "target": "dmg" // macOS 输出格式（dmg 安装包） }, "win": { "target": "nsis" // Windows 输出格式（nsis 安装包） }, "linux": { "target": "deb" // Linux 输出格式（deb 包，适用于 Ubuntu 等） } }, "devDependencies": { "electron": "^31.0.1", "electron-builder": "^24.13.3", "vite": "^5.4.8", "vite-plugin-electron": "^0.28.4" } }
四、开发与调试
1. 启动开发环境（支持热重载）
npm run dev
- 成功标志：自动弹出 Electron 窗口，显示页面内容，修改 index.html 或 main.js 会实时更新。
- 调试：开发环境默认打开 Chrome 开发者工具，可查看控制台日志。
五、打包多平台安装包
1. 打包前准备（可选）
- 若需自定义图标，在项目根目录创建 build/icons 文件夹，放入对应格式图标：
-
- macOS：icon.icns
- Windows：icon.ico
- Linux：icon.png并在 main.js 的窗口配置中添加 icon 路径（参考前文示例）。
2. 执行打包命令
npm run build
- 打包过程：先通过 vite build 打包前端资源到 dist 目录，再通过 electron-builder 生成对应平台的安装包。
- 输出位置：安装包会生成在 release 目录下（如 release/ElectronViteApp-1.0.0.dmg 等）。
六、验证打包结果
- macOS：双击 release/*.dmg，拖拽应用到 Applications 文件夹即可安装。
- Windows：运行 release/*.exe 安装包（需在 Windows 系统或通过 wine 模拟）。
- Linux：通过 sudo dpkg -i release/*.deb 安装（适用于 Debian/Ubuntu 系统）。
总结
通过以上步骤，可完成从 项目初始化 到 多平台打包 的全流程，核心优势：
- 开发阶段支持热重载（修改代码实时生效）。
- 一次配置，自动生成 macOS/Windows/Linux 安装包。
- 遵循 Electron 安全最佳实践（禁用 Node 集成、启用上下文隔离）。
如果打包过程中遇到平台相关问题（如 Windows 包在 macOS 上构建失败），可参考 electron-builder 文档配置跨平台构建依赖。
