将已有 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.html
    win.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', {
  // 可以在这里暴露一些方法，如打开文件、调用系统 API
  doThing: () => 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

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

🎯 四、进阶建议

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

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

2. 支持原生功能

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

3. 自动更新

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

📈 五、总结

💬 结语

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

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

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

📌 推荐阅读：

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