从浏览器到桌面：Vue2 项目无缝升级为 Windows 桌面应用（Electron 实战教程）
很多开发者基于 Vue2 + Element UI 开发的管理系统、工具类应用，往往需要从网页端延伸到桌面端 —— 既想保留 Vue 的开发体验，又要具备桌面应用的本地权限（文件读写、系统托盘、快捷键等）。
本文将带来生产级实战教程，手把手教你把 Vue2 项目打包成 Windows 桌面应用（EXE 安装包），覆盖 Electron 集成、本地权限调用、打包优化、自动更新四大核心场景，所有代码可直接复用，适配管理系统、工具类应用等主流场景。
一、核心选型：为什么选 Electron？
Vue2 项目转桌面应用，Electron 是最优选择，没有之一：
✅ 完全兼容 Vue 生态：无需重构 Vue 代码，仅需新增 Electron 层；
✅ 跨平台：一套代码可打包 Windows/macOS/Linux；
✅ 完整的桌面能力：文件读写、系统托盘、快捷键、注册表操作等；
✅ 成熟的打包工具：支持生成 EXE 安装包、绿色版、自动更新。

二、前期准备：环境与项目结构调整
2.1 环境要求
Node.js ≥ 14.x（建议 16.x LTS，避免 Electron 兼容问题）；
Vue2 项目（已基于 vue-cli 构建，本文以 vue-cli 3/4 为例）；
依赖工具：electron、electron-builder（打包）、electron-updater（自动更新）。
2.2 项目结构改造
原有 Vue2 项目结构：
plaintext
vue2-project/
├── src/ # Vue源码
├── public/ # 静态资源
├── package.json # Vue依赖
└── vue.config.js # Vue配置
改造后新增 Electron 相关目录：
plaintext
vue2-project/
├── src/
├── public/
├── electron/ # 新增：Electron核心代码
│ ├── main.js # 主进程（桌面应用入口）
│ └── preload.js # 预加载脚本（渲染进程与主进程通信）
├── package.json # 新增Electron相关配置
├── vue.config.js
└── electron-builder.json # 打包配置
三、实战步骤：Electron 集成 Vue2 项目
步骤 1：安装核心依赖
在 Vue2 项目根目录执行：
bash
运行

安装Electron（指定稳定版，避免兼容性问题）

npm install electron@18.3.7 --save-dev

安装打包工具

npm install electron-builder@23.6.0 --save-dev

安装自动更新（可选）

npm install electron-updater --save

安装跨进程通信辅助包（可选，简化ipc通信）

npm install electron-ipc-helper --save
步骤 2：配置 package.json
修改 Vue 项目的package.json，新增 Electron 启动、打包脚本，并补充必要配置：
json
{
“name”: “vue2-electron-app”,
“version”: “1.0.0”,
“main”: “electron/main.js”, // Electron入口文件
“scripts”: {
// 原有Vue启动脚本
“serve”: “vue-cli-service serve”,
“build”: “vue-cli-service build”,
// 新增Electron脚本
“electron:serve”: “vue-cli-service build && electron .”, // 开发调试（先打包Vue再启动Electron）
“electron:build”: “vue-cli-service build && electron-builder” // 打包成EXE
},
// Electron-builder基础配置（也可抽离到electron-builder.json）
“build”: {
“appId”: “com.xxx.vue2-electron”, // 唯一标识（反向域名格式）
“productName”: “Vue2桌面应用”, // 应用名称（显示在桌面）
“copyright”: “Copyright © 2026 ${author}”, // 版权信息
“directories”: {
“output”: “dist_electron” // 打包输出目录
},
“nsis”: { // Windows安装包配置
“oneClick”: false, // 取消一键安装（让用户选择安装路径）
“allowToChangeInstallationDirectory”: true, // 允许修改安装路径
“installerIcon”: “public/favicon.ico”, // 安装包图标
“uninstallerIcon”: “public/favicon.ico”, // 卸载图标
“installerHeaderIcon”: “public/favicon.ico” // 安装头部图标
},
“win”: { // Windows打包配置
“icon”: “public/favicon.ico”, // 应用图标
“target”: [
{
“target”: “nsis”, // 生成EXE安装包
“arch”: [“x64”] // 仅64位（适配主流Windows）
}
]
}
}
}
步骤 3：编写 Electron 主进程（electron/main.js）
主进程是桌面应用的核心，负责窗口创建、系统权限调用、与 Vue 渲染进程通信：
javascript
运行
// electron/main.js
const { app, BrowserWindow, ipcMain, Tray, Menu } = require(‘electron’)
const path = require(‘path’)
const fs = require(‘fs’)

// 禁用Electron安全警告（生产环境建议保留）
process.env.ELECTRON_DISABLE_SECURITY_WARNINGS = ‘true’

// 全局窗口实例（防止被GC回收）
let mainWindow = null
// 系统托盘实例
let tray = null

// 创建主窗口
function createWindow() {
mainWindow = new BrowserWindow({
width: 1200, // 窗口初始宽度
height: 800, // 窗口初始高度
minWidth: 800, // 最小宽度
minHeight: 600, // 最小高度
webPreferences: {
nodeIntegration: false, // 禁用渲染进程Node集成（安全）
contextIsolation: true, // 开启上下文隔离
preload: path.join(__dirname, ‘preload.js’) // 预加载脚本（通信桥）
},
icon: path.join(__dirname, ‘…/public/favicon.ico’), // 窗口图标
show: false // 先隐藏窗口，加载完成后再显示（避免白屏）
})

// 加载Vue打包后的静态文件（开发/生产环境兼容）
if (process.env.NODE_ENV === ‘development’) {
// 开发环境：加载Vue本地开发服务
mainWindow.loadURL(‘http://localhost:8080’)
// 开启调试工具
mainWindow.webContents.openDevTools()
} else {
// 生产环境：加载打包后的index.html
mainWindow.loadFile(path.join(__dirname, ‘…/dist/index.html’))
}

// 窗口加载完成后显示
mainWindow.webContents.on(‘did-finish-load’, () => {
mainWindow.show()
})

// 窗口关闭事件
mainWindow.on(‘closed’, () => {
mainWindow = null
})

// 系统托盘配置（可选）
createTray()
}

// 创建系统托盘（桌面右下角图标）
function createTray() {
tray = new Tray(path.join(__dirname, ‘…/public/favicon.ico’))
// 托盘右键菜单
const contextMenu = Menu.buildFromTemplate([
{
label: ‘显示窗口’,
click: () => {
mainWindow.show()
}
},
{
label: ‘退出’,
click: () => {
app.quit()
}
}
])
tray.setToolTip(‘Vue2桌面应用’) // 托盘提示
tray.setContextMenu(contextMenu) // 绑定右键菜单
// 双击托盘显示窗口
tray.on(‘double-click’, () => {
mainWindow.show()
})
}

// 监听Vue渲染进程的IPC请求（示例：文件读写）
ipcMain.handle(‘fs:readFile’, async (event, filePath) => {
try {
// 读取本地文件（桌面应用核心权限）
const content = fs.readFileSync(filePath, ‘utf8’)
return { code: 200, data: content }
} catch (err) {
return { code: 500, message: err.message }
}
})

ipcMain.handle(‘fs:writeFile’, async (event, filePath, content) => {
try {
fs.writeFileSync(filePath, content, ‘utf8’)
return { code: 200, message: ‘写入成功’ }
} catch (err) {
return { code: 500, message: err.message }
}
})

// 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()
})
步骤 4：编写预加载脚本（electron/preload.js）
预加载脚本是渲染进程（Vue）与主进程（Electron）的安全通信桥，避免直接暴露 Node API：
javascript
运行
// electron/preload.js
const { contextBridge, ipcRenderer } = require(‘electron’)

// 向Vue渲染进程暴露安全的API
contextBridge.exposeInMainWorld(‘electronAPI’, {
// 文件读取
readFile: (filePath) => ipcRenderer.invoke(‘fs:readFile’, filePath),
// 文件写入
writeFile: (filePath, content) => ipcRenderer.invoke(‘fs:writeFile’, filePath, content),
// 窗口最小化
minimizeWindow: () => ipcRenderer.send(‘window:minimize’),
// 窗口最大化/还原
toggleMaximizeWindow: () => ipcRenderer.send(‘window:toggleMaximize’),
// 窗口关闭
closeWindow: () => ipcRenderer.send(‘window:close’)
})
步骤 5：Vue2 项目中调用桌面能力
无需重构原有 Vue 代码，仅需在需要桌面权限的地方调用window.electronAPI：
vue

步骤 6：开发调试与打包
6.1 开发调试（热更新）
bash
运行

第一步：启动Vue本地服务

npm run serve

第二步：新开终端，启动Electron（加载Vue服务）

npm run electron:serve
此时会启动桌面窗口，且 Vue 代码修改后会热更新（和网页端一致）。
6.2 打包成 Windows EXE 安装包
bash
运行

打包Vue代码 + 打包Electron成EXE

npm run electron:build
打包完成后，dist_electron目录下会生成：
vue2-electron-app Setup 1.0.0.exe：可安装的 EXE 包；
win-unpacked目录：绿色版（无需安装，直接运行vue2-electron-app.exe）。
四、核心优化：解决 Electron 打包痛点
4.1 减小打包体积（从 80MB→40MB）
Electron 打包体积大是通病，通过以下优化可大幅压缩：
剔除无用依赖：在package.json中把非核心依赖移到devDependencies；
压缩 asar 包：修改electron-builder.json开启压缩：
json
{
“asar”: true,
“asarUnpack”: [“**/*.node”] // 保留原生模块不压缩
}
使用 Electron 镜像：新增.npmrc文件，加速 Electron 下载：
plaintext
electron_mirror=https://npmmirror.com/mirrors/electron/
electron_builder_binaries_mirror=https://npmmirror.com/mirrors/electron-builder-binaries/
4.2 解决 Vue 路由刷新 404 问题
Vue 项目若使用history路由，打包后桌面应用刷新会 404，修改vue.config.js：
javascript
运行
module.exports = {
// 打包路径适配Electron
publicPath: ‘./’,
// 路由模式强制为hash（桌面应用推荐）
configureWebpack: {
resolve: {
alias: {
‘path’: ‘path-browserify’ // 解决path模块找不到问题
}
}
}
}
4.3 本地权限扩展（进阶）
除了文件读写，还可通过 Electron 实现更多桌面能力：
javascript
运行
// 1. 注册全局快捷键（main.js）
const { globalShortcut } = require(‘electron’)
app.whenReady().then(() => {
// 注册Ctrl+Shift+I打开调试工具
globalShortcut.register(‘Ctrl+Shift+I’, () => {
mainWindow.webContents.openDevTools()
})
})

// 2. 调用Windows系统对话框（preload.js暴露API）
contextBridge.exposeInMainWorld(‘electronAPI’, {
openFileDialog: () => ipcRenderer.invoke(‘dialog:openFile’)
})

// main.js监听
ipcMain.handle(‘dialog:openFile’, async () => {
const { dialog } = require(‘electron’)
const result = await dialog.showOpenDialog({
properties: [‘openFile’, ‘multiSelections’],
filters: [{ name: ‘文本文件’, extensions: [‘txt’, ‘json’] }]
})
return result.filePaths
})
五、生产级必备：自动更新功能
桌面应用必须支持自动更新，基于electron-updater实现：
5.1 配置更新服务器（以阿里云 OSS 为例）
在 OSS 创建 Bucket，开启公网访问；
打包后的更新文件（latest.yml、exe）上传至 OSS；
修改electron-builder.json添加更新配置：
json
{
“publish”: {
“provider”: “generic”,
“url”: “https://your-oss-bucket.oss-cn-shanghai.aliyuncs.com/updates/”
}
}
5.2 主进程添加更新逻辑（main.js）
javascript
运行
const { autoUpdater } = require(‘electron-updater’)

// 自动更新配置
function setupAutoUpdate() {
// 开启更新日志
autoUpdater.logger = require(‘electron-log’)
autoUpdater.logger.transports.file.level = ‘info’

// 检查更新
autoUpdater.checkForUpdatesAndNotify()

// 更新事件监听
autoUpdater.on(‘update-available’, (info) => {
mainWindow.webContents.send(‘update:available’, info)
})

autoUpdater.on(‘update-downloaded’, (info) => {
mainWindow.webContents.send(‘update:downloaded’, info)
// 提示用户重启更新
ipcMain.on(‘update:install’, () => {
autoUpdater.quitAndInstall()
})
})

autoUpdater.on(‘error’, (err) => {
mainWindow.webContents.send(‘update:error’, err.message)
})
}

// 在createWindow后调用
app.whenReady().then(() => {
createWindow()
setupAutoUpdate() // 启动自动更新
})
5.3 Vue 端接收更新通知
vue

六、常见问题与解决方案
问题 现象 解决方案
打包后白屏 窗口显示空白，无内容 1. 检查vue.config.js的publicPath设为./；2. 确认 Electron 加载的是dist/index.html；3. 开启调试工具查看报错
本地文件读写失败 提示权限不足 1. 确保文件路径正确（使用path模块拼接）；2. 避免读写系统盘根目录（如 C:\）；3. 以管理员身份运行应用
打包体积过大 EXE 包超过 100MB 1. 开启 asar 压缩；2. 剔除node_modules中无用依赖；3. 使用electron-builder的win.zip压缩
自动更新失败 提示无法连接更新服务器 1. 检查 OSS 文件路径是否正确；2. 确保latest.yml与 EXE 版本一致；3. 关闭防火墙 / 代理
七、总结与扩展
本文实现的 Vue2 转 Windows 桌面应用方案，核心是Electron 作为外壳，Vue 作为内核：
无需重构 Vue 代码，仅需新增 Electron 层即可获得桌面能力；
覆盖了开发调试、打包优化、本地权限、自动更新四大生产级需求；
适配管理系统、工具类应用等主流 Vue2 项目场景。