将已有 Vue 项目通过 Electron 打包为桌面客户端的完整步骤

🌟 前言

你是否有一个已经开发好的 Vue 项目（如管理后台、工具类应用、个人博客），想让它脱离浏览器，变成一个双击即可运行的桌面客户端？比如像 VS Code、网易云音乐那样运行在 Windows、macOS 或 Linux 上？

✅ Electron 正是为此而生！它允许你使用前端技术（HTML/CSS/JavaScript）构建跨平台桌面应用。

本文将手把手教你：如何将一个已有的 Vue 项目（Vue CLI 或 Vite 构建）通过 Electron 打包成可执行的桌面客户端，无需从头开始，适合初级到中级前端开发者。

---

📦 一、整体思路

Electron 应用由两个核心部分组成：

• 主进程（Main Process）：负责创建窗口、管理应用生命周期（Node.js 环境）
• 渲染进程（Renderer Process）：负责 UI 界面，就是你的 Vue 项目（浏览器环境）

我们的目标是：

1. 保留原有 Vue 项目不动
2. 新增 Electron 主进程
3. 将 Vue 打包后的静态文件交给 Electron 加载
4. 使用打包工具生成 .exe（Windows）、.dmg（macOS）等可执行文件

---

🚀 二、具体操作步骤

✅ 步骤 1：准备已有 Vue 项目

假设你已有一个 Vue 项目（使用 Vue CLI 或 Vite 构建），项目结构如下：

my-vue-project/
├── public/
├── src/
├── package.json
└── (vue.config.js 或 vite.config.js)

确保项目可以正常运行：

npm run serve  # 或 npm run dev

---

✅ 步骤 2：安装 Electron

在项目根目录安装 Electron（作为开发依赖）：

npm install electron --save-dev

✅ 推荐版本：Electron 28+（支持最新 Node.js 和 Chromium）

---

✅ 步骤 3：创建 Electron 主进程文件

在项目根目录创建 electron/ 文件夹，用于存放 Electron 相关代码：

mkdir electron

创建主进程入口文件：electron/main.js

// electron/main.js
const { app, BrowserWindow } = require('electron')
const path = require('path')// 创建主窗口
function createWindow () {const win = new BrowserWindow({width: 1200,height: 800,webPreferences: {// 禁用 nodeIntegration 出于安全考虑nodeIntegration: false,// 启用上下文隔离（推荐）contextIsolation: true,// 预加载脚本（可选）preload: path.join(__dirname, 'preload.js')}})// 判断是开发环境还是生产环境if (process.env.NODE_ENV === 'development') {// 开发模式：加载本地 Vue 服务win.loadURL('http://localhost:8080') // 注意：Vue CLI 默认端口是 8080，Vite 是 5173} else {// 生产模式：加载打包后的 index.htmlwin.loadFile(path.join(__dirname, '../dist/index.html'))}
}// Electron 初始化完成后创建窗口
app.whenReady().then(() => {createWindow()// macOS 规范app.on('activate', () => {if (BrowserWindow.getAllWindows().length === 0) createWindow()})
})// 关闭所有窗口时退出应用（Windows 和 Linux）
app.on('window-all-closed', () => {if (process.platform !== 'darwin') app.quit()
})

⚠️ 注意：loadURL 的端口根据你的 Vue 项目配置调整（Vue CLI: 8080，Vite: 5173）。

---

✅ 步骤 4：创建预加载脚本（可选但推荐）

创建 electron/preload.js（增强安全性）：

// electron/preload.js
const { contextBridge } = require('electron')// 安全地暴露 API 给渲染进程
contextBridge.exposeInMainWorld('electron', {// 可以在这里暴露一些方法，如打开文件、调用系统 APIdoThing: () => console.log('执行 Electron 功能')
})

之后在 Vue 页面中可通过 window.electron.doThing() 调用。

---

✅ 步骤 5：配置 package.json

修改项目根目录的 package.json，添加 Electron 相关配置：

{"name": "my-vue-electron-app","version": "1.0.0","main": "electron/main.js","scripts": {"serve": "vue-cli-service serve",     // Vue CLI 项目"build": "vue-cli-service build",     // Vue CLI 项目"dev:electron": "set NODE_ENV=development && electron .","build:electron": "npm run build && electron-builder","start": "electron ."},"devDependencies": {"electron": "^28.0.0","electron-builder": "^24.0.0"}
}

🔁 如果你使用的是 Vite，build 脚本可能是 vite build。

---

✅ 步骤 6：安装打包工具（推荐 electron-builder）

npm install electron-builder --save-dev

electron-builder 可以一键打包成 .exe、.dmg、.AppImage 等格式。

---

✅ 步骤 7：配置打包选项

在 package.json 中添加 build 字段：

"build": {"appId": "com.yourname.myapp","productName": "My Vue App","copyright": "Copyright © 2025 ${author}","directories": {"output": "dist-electron"},"files": ["electron/**/*","dist/**/*"],"win": {"target": "nsis","icon": "public/icon.ico"  // Windows 图标（建议 256x256）},"mac": {"target": "dmg","icon": "public/icon.icns"  // macOS 图标},"linux": {"target": "AppImage","icon": "public/icon.png"}
}

📌 提示：可在 public/ 目录下准备不同格式的图标文件。

---

✅ 步骤 8：运行与打包

1. 开发模式（调试）

先启动 Vue 项目：

npm run serve   # 或 npm run dev (Vite)

另开一个终端，启动 Electron：

npm run dev:electron

你会看到 Electron 窗口加载了你的 Vue 应用，可以正常交互。

2. 生产打包

npm run build:electron

打包完成后，会在 dist-electron/ 目录下生成可执行文件：

• Windows：my-vue-app Setup 1.0.0.exe
• macOS：My Vue App.dmg
• Linux：My Vue App.AppImage

---

⚠️ 三、常见问题与注意事项

问题	解决方案
❗ 打包后白屏	检查 main.js 中 loadFile 路径是否正确，建议使用 path.join
❗ 开发模式端口错误	确保 Vue 服务端口与 main.js 中 loadURL 一致
❗ 图标不显示	确保图标路径正确，格式符合要求（.ico/.icns/.png）
❗ 文件过大	Electron 默认体积较大（80~150MB），可接受
❗ 安全警告	禁用 nodeIntegration，使用 contextBridge 暴露 API

---

🎯 四、进阶建议

1. 使用 vue-cli-plugin-electron-builder（Vue CLI 用户）

   • 插件自动集成 Electron，简化配置
   • 安装：vue add electron-builder

2. 支持原生功能

   • 调用系统对话框、文件系统、托盘图标等
   • 通过 preload.js + contextBridge 实现

3. 自动更新

   • 使用 electron-updater 实现应用自动更新

---

📈 五、总结

步骤	关键点
1. 保留 Vue 项目	不修改原有代码
2. 新增 electron/main.js	主进程入口
3. 配置 package.json	设置主文件和脚本
4. 使用 electron-builder 打包	生成可执行文件
5. 调试与发布	开发模式 + 生产打包

---

💬 结语

通过 Electron，你可以轻松将 Vue 项目变成桌面客户端，实现“一次开发，多端运行”。虽然打包体积较大，但对于工具类、内部系统、个人项目来说，是非常实用的方案。

赶快动手试试吧！你的第一个桌面应用，就从今天开始！

---

如果你觉得这篇文章对你有帮助，欢迎点赞、收藏、转发！
也欢迎在评论区分享你的打包经验或遇到的问题，我们一起交流进步！

---

📌 推荐阅读：

• 《Electron 官方文档中文版》
• 《Vue 3 全家桶实战》
• 《Vite 从入门到精通》