Vue3 + Vite + Electron 桌面应用开发完整指南：从项目创建到打包分发

Electron 是什么？

Electron 是一个使用 JavaScript、HTML 和 CSS 构建桌面应用程序的框架。它通过将 Chromium 和 Node.js 嵌入到一个二进制文件中，让你可以仅维护一个 JavaScript 代码库，就能创建在 Windows、macOS 和 Linux 上运行的跨平台应用，而无需掌握原生开发经验。它基于 MIT 开源许可证，对商业和个人用途均免费。

一、创建 Vue 项目

以下是基于 Vue3、Vite 和 JavaScript 技术栈创建项目的步骤。

两种创建方式（任选其一）：

1. Vue 官方工具创建（推荐）

pnpm create vue

# 1. 给项目命名
# 2. 选择你需要的配置

# 进入项目
cd 项目名
# 安装所需的依赖
pnpm i
# 启动项目
pnpm dev

2. Vite 创建

pnpm create vite

# 1. 给项目命名
# 2. 选择对应的框架语言（Vue）
# 3. 选择创建 vue 的方式（Official Vue Starter）
# 4. 选择你需要的配置

# 进入项目目录
cd 项目名
# 安装所需的依赖
pnpm i
# 启动项目
pnpm dev

创建项目后，正常书写你的网页代码即可。

二、使用 Electron 框架打包

假设我的项目已经完成，目标是将其打包成独立的桌面应用。

1. 安装 electron 依赖包

在项目根目录下，安装 Electron 和 Electron-Builder 开发依赖。

# 在项目安装 Electron 和 Electron-Builder 依赖
pnpm i electron electron-builder --save-dev

2. 初始化项目主进程

在项目根目录创建 electron-main.js 文件，作为 Electron 应用的主进程入口，内容如下：

import { app, Menu, BrowserWindow } from 'electron';
import path from 'path';

// 创建窗口
function createWindow() {
  const win = new BrowserWindow({
    width: 1200,  // 打开的默认宽
    height: 800,  // 打开的默认高
    autoHideMenuBar: false, // 是否隐藏默认菜单
    webPreferences: {
      nodeIntegration: true,
      contextIsolation: false,
      webSecurity: false, // 允许加载本地文件
    },
    show: false, // 先不显示，等加载完成后再显示
  });

  const appPath = app.getAppPath();
  // 使用 loadFile，它会自动处理路径
  win.loadFile(path.join(appPath, 'dist', 'index.html'))

  // 检测系统语言
  const systemLocale = app.getLocale()
  // 设置应用的语言
  const isChinese = systemLocale.startsWith('zh')
  // 判断系统使用哪个语言
  const template = isChinese ? getChineseMenu() : getEnglishMenu()
  // 应用菜单栏
  const menu = Menu.buildFromTemplate(template)
  // 设置菜单栏
  Menu.setApplicationMenu(menu)

  // 页面加载完成后显示窗口
  win.once('ready-to-show', () => {
    win.show();
  });
}

// 所有窗口关闭时退出（macOS 除外）
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});
// macOS 上点击 dock 图标时重新创建窗口
app.on('activate', () => {
  if (BrowserWindow.getAllWindows().length === 0) {
    createWindow();
  }
});

// 调用创建窗口
app.on('ready', createWindow)

// 这是中文设置
function getChineseMenu() {
  return [
    {
      label: '文件',
      submenu: [
        {
          label: '新建窗口',
          accelerator: 'CmdOrCtrl+N',
          click: () => {
            // 新建窗口逻辑
          }
        },
        { type: 'separator' },
        {
          label: '退出',
          accelerator: 'CmdOrCtrl+Q',
          click: () => app.quit()
        }
      ]
    },
    {
      label: '编辑',
      submenu: [
        { label: '撤销', role: 'undo' },
        { label: '重做', role: 'redo' },
        { type: 'separator' },
        { label: '剪切', role: 'cut' },
        { label: '复制', role: 'copy' },
        { label: '粘贴', role: 'paste' },
        { label: '全选', role: ‘selectAll‘ }
      ]
    },
    {
      label: ‘视图‘,
      submenu: [
        { label: ‘刷新‘, role: ‘reload‘ },
        { label: ‘开发者工具‘, role: ‘toggleDevTools‘ },
        { type: ‘separator‘ },
        { label: ‘重置缩放‘, role: ‘resetZoom‘ },
        { label: ‘放大‘, role: ‘zoomIn‘ },
        { label: ‘缩小‘, role: ‘zoomOut‘ }
      ]
    },
    {
      label: ‘窗口‘,
      submenu: [
        { label: ‘最小化‘, role: ‘minimize‘ },
        { label: ‘关闭‘, role: ‘close‘ }
      ]
    },
    {
      label: ‘帮助‘,
      submenu: [
        {
          label: ‘关于‘,
          click: () => {
            // 显示关于对话框
          }
        }
      ]
    }
  ]
}

3. 创建构建脚本与应用配置信息

修改 package.json 文件，在 scripts 字段中添加 Electron 相关命令，并添加 build 配置字段。

{
  "name": "vite-project",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "engines": {
    "node": "^20.19.0 || >=22.12.0"
  },
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "electron:dev": "electron .",
    "electron:build": "electron-builder"
  },
  "main": "electron-main.js",
  "build": {
    "appId": "com.example.app",
    "productName": "测试应用",
    "copyright": "Copyright © 2025",
    "directories": {
      "output": "release"
    },
    "files": [
      "dist/**/*",
      "electron-main.js",
      "package.json"
    ],
    "win": {
      "icon": "./favicon.ico",
      "target": [
        {
          "target": "nsis",
          "arch": ["x64"]
        }
      ]
    },
    "nsis": {
      "oneClick": false,
      "allowToChangeInstallationDirectory": true
    }
  },
  "dependencies": {
    "vue": "^3.5.25"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^6.0.2",
    "electron": "^39.2.7",
    "electron-builder": "^26.0.12",
    "vite": "^7.2.4",
    "vite-plugin-vue-devtools": "^8.0.5"
  }
}

配置说明：

// electron预览
"electron:dev": "electron .",
// 64位的打包
"electron:build": "electron-builder",
// 32位的打包（如需）
"electron:build32": "electron-builder --win --ia32"

图标配置规范：

• mac：icon.icns 或 icon.png (512 * 512)
• win：icon.ico 或 icon.png (256 * 256)
• linux：icon.png (256 * 256)

4. 开发预览与调试

运行以下命令，在开发模式下预览 Electron 桌面应用。

pnpm electron:dev

可能遇到的问题：

• 报错：Electron failed to install correctly, please delete node_modules/electron and try installing again
• 现象：卡在 node install.js 步骤长时间不动。

原因：这通常是由于 node_modules/electron 目录中的文件丢失或损坏导致程序无法正常执行。

解决方案：使用 electron-fix 自动修复工具。

# 1. 全局安装 electron-fix 工具
pnpm i -g electron-fix

# 2. 在项目根目录执行修复
electron-fix start

5. 构建打包

打包分为两步：先打包网页资源，再打包 Electron 应用。

pnpm build
pnpm electron:build

构建完成后，会在项目根目录生成一个 release 文件夹：

1. win-unpacked：绿色免安装版，可直接运行。

2. 测试应用 Setup 0.0.0.exe：Windows 安装包，点击即可安装。
   

3. 安装完成后，即可在桌面或开始菜单找到应用图标并打开。
   

打包注意事项:

1. 依赖项：确保项目中所有依赖项都已正确安装。
2. 资源路径：检查图片、配置文件等资源的路径是否正确，打包后文件结构可能改变。
3. 跨平台兼容性：如果计划支持多个平台，请确保代码和资源在不同平台上都能正常工作。

三、常见问题与解决方案

各种依赖包的国内镜像地址： https://registry.npmmirror.com/binary.html

1. 缺失 Electron 安装包

下载链接：https://registry.npmmirror.com/binary.html?path=electron/

选择对应版本（例如 electron-v39.2.7-win32-x64.zip），将其放入本地缓存目录：
C:\Users\[你的用户名]\AppData\Local\electron\Cache

2. 解决 electron-builder 构建报错（网络超时）

在构建过程中，可能会因为网络问题无法从 GitHub 下载必要的构建工具包。

错误现象：终端卡在 downloading 步骤，并提示连接超时。

解决方案：手动下载依赖包

（1）解决 winCodeSign-2.6.0.7z 下载问题

• 下载链接：https://github.com/electron-userland/electron-builder-binaries/releases/tag/winCodeSign-2.6.0
• 放置路径：C:\Users\[你的用户名]\AppData\Local\electron-builder\Cache\winCodeSign\
• 要求：将下载的 winCodeSign-2.6.0.7z 解压，并将文件夹重命名为 winCodeSign-2.6.0 放入上述路径。

（2）解决 nsis-3.0.4.1.7z 和 nsis-resources-3.4.1.7z 下载问题
手动放置上述包后，再次构建可能遇到新的网络错误。

• nsis-3.0.4.1 下载链接：https://github.com/electron-userland/electron-builder-binaries/releases/tag/nsis-3.0.4.1
• nsis-resources-3.4.1 下载链接：https://github.com/electron-userland/electron-builder-binaries/releases/tag/nsis-resources-3.4.1
• 放置路径：C:\Users\[你的用户名]\AppData\Local\electron-builder\Cache\nsis\
• 要求：分别下载两个压缩包，解压后得到 nsis-3.0.4.1 和 nsis-resources-3.4.1 文件夹，放入上述 nsis 目录。

手动放置所有必要文件后，再次执行构建命令即可成功。

pnpm electron:build

各平台缓存目录路径：

• Linux：$XDG_CACHE_HOME 或 ~/.cache/electron/
• macOS：~/Library/Caches/electron/
• Windows：%LOCALAPPDATA%/electron-builder/Cache (通常是 C:\Users\[用户名]\AppData\Local\electron-builder\Cache)

3. Electron 打包后应用白屏问题及解决方案

可能原因：主进程中加载的页面地址错误。例如，在开发时使用 loadURL(‘http://localhost:8080’)，但打包后没有这个服务。

解决方案：

（1）检查并修正资源加载路径
确保使用 loadFile 并配合 path.join 或 __dirname 来定位打包后的静态文件。

const path = require('path');
mainWindow.loadFile(path.join(__dirname, 'dist', 'index.html'));

（2）优化窗口加载时机
确保页面完全加载后再显示窗口，避免短暂白屏。

app.whenReady().then(() => {
  const mainWindow = new BrowserWindow({ show: false });
  mainWindow.loadFile('index.html');
  mainWindow.once('ready-to-show', () => {
    mainWindow.show();
  });
});

（3）检查打包配置

• 确认 electron-builder 配置中的 files 字段包含了所有必需文件（如 dist 目录）。
• 如果使用了 asar 归档，请测试资源文件是否能被正确读取。

总结与资源索引

通过上述步骤，你可以将一个 Vue3 网页项目成功打包为跨平台的 Electron 桌面应用。整个过程涉及前端构建、Node.js 主进程配置和桌面端打包，是整合现代Web技术与桌面开发的良好实践。如果在实践中遇到其他问题，欢迎在 云栈社区 与更多开发者交流探讨。

本文用到的关键资源下载地址：

• Electron 安装包：https://registry.npmmirror.com/binary.html?path=electron/
• winCodeSign-2.6.0：https://github.com/electron-userland/electron-builder-binaries/releases/tag/winCodeSign-2.6.0
• nsis-3.0.4.1：https://github.com/electron-userland/electron-builder-binaries/releases/tag/nsis-3.0.4.1
• nsis-resources-3.4.1：https://github.com/electron-userland/electron-builder-binaries/releases/tag/nsis-resources-3.4.1