Vue 3 与 Electron 桌面应用开发

概述

Electron 是一个使用 JavaScript、HTML 和 CSS 构建跨平台桌面应用的框架，它基于 Chromium 和 Node.js，允许开发者使用 Web 技术创建桌面应用。Vue 3 与 Electron 的结合可以充分发挥两者的优势，既可以利用 Vue 3 的现代化开发体验，又可以获得原生桌面应用的能力。本集将详细介绍如何使用 Vue 3 和 Electron 构建桌面应用。

核心知识点

1. Electron 基础架构

• 主进程（Main Process）：管理窗口、菜单、托盘等原生桌面功能
• 渲染进程（Renderer Process）：运行 Vue 应用的 Chromium 实例
• 预加载脚本（Preload Script）：连接主进程和渲染进程的桥梁
• IPC（Inter-Process Communication）：主进程和渲染进程之间的通信机制

2. Vue 3 + Electron 项目初始化

使用 Vite + Electron 模板

# 使用官方模板创建项目
yarn create vite my-electron-app -- --template vue
cd my-electron-app

# 安装 Electron 相关依赖
yarn add -D electron electron-builder vite-plugin-electron

配置 Vite 插件

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import electron from 'vite-plugin-electron'

export default defineConfig({
  plugins: [
    vue(),
    electron({
      main: {
        entry: 'electron/main.js'
      },
      preload: {
        input: {
          preload: 'electron/preload.js'
        }
      }
    })
  ]
})

3. Electron 主进程配置

创建主进程文件

// electron/main.js
const { app, BrowserWindow } = require('electron')
const path = require('path')

function createWindow () {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
      enableRemoteModule: false,
      nodeIntegration: false
    }
  })

  // 加载 Vite 开发服务器
  if (process.env.VITE_DEV_SERVER_URL) {
    win.loadURL(process.env.VITE_DEV_SERVER_URL)
    win.webContents.openDevTools()
  } else {
    // 加载打包后的文件
    win.loadFile(path.join(__dirname, '../dist/index.html'))
  }
}

app.whenReady().then(() => {
  createWindow()

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) {
      createWindow()
    }
  })
})

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit()
  }
})

4. 预加载脚本配置

创建预加载脚本

// electron/preload.js
const { contextBridge, ipcRenderer } = require('electron')

// 向渲染进程暴露安全的 API
contextBridge.exposeInMainWorld('electronAPI', {
  // 接收主进程消息
  onUpdateCounter: (callback) => ipcRenderer.on('update-counter', callback),
  // 发送消息到主进程
  incrementCounter: () => ipcRenderer.send('increment-counter')
})

5. Vue 3 应用与 Electron 集成

在 Vue 组件中使用 Electron API

<template>
  <div class="container">
    <h1>Vue 3 + Electron App</h1>
    <p>Counter: {{ counter }}</p>
    <button @click="increment">Increment</button>
    <button @click="openDialog">Open Dialog</button>
  </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'

const counter = ref(0)

// 使用 Electron API
const increment = () => {
  if (window.electronAPI) {
    window.electronAPI.incrementCounter()
  }
}

const openDialog = async () => {
  if (window.electronAPI) {
    const result = await window.electronAPI.openDialog()
    console.log('Dialog result:', result)
  }
}

// 监听主进程消息
const handleUpdateCounter = (event, value) => {
  counter.value = value
}

onMounted(() => {
  if (window.electronAPI) {
    window.electronAPI.onUpdateCounter(handleUpdateCounter)
  }
})

onUnmounted(() => {
  if (window.electronAPI) {
    // 移除事件监听
    window.electronAPI.removeUpdateCounterListener(handleUpdateCounter)
  }
})
</script>

<style scoped>
.container {
  text-align: center;
  margin-top: 50px;
}

button {
  margin: 10px;
  padding: 8px 16px;
  background-color: #42b883;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}
</style>

6. IPC 通信机制

主进程监听和发送消息

// electron/main.js
const { ipcMain, dialog } = require('electron')

let counter = 0

// 监听渲染进程消息
ipcMain.on('increment-counter', (event) => {
  counter++
  // 发送消息到渲染进程
  event.reply('update-counter', counter)
})

// 处理对话框请求
ipcMain.handle('open-dialog', async (event) => {
  const result = await dialog.showOpenDialog({
    properties: ['openFile', 'multiSelections']
  })
  return result
})

渲染进程使用 IPC

// 在预加载脚本中暴露更多 API
contextBridge.exposeInMainWorld('electronAPI', {
  // 异步 IPC
  openDialog: () => ipcRenderer.invoke('open-dialog'),
  // 事件监听和移除
  onUpdateCounter: (callback) => {
    ipcRenderer.on('update-counter', callback)
    return () => ipcRenderer.removeListener('update-counter', callback)
  }
})

7. 打包和分发

配置 electron-builder

// package.json
{
  "name": "my-electron-app",
  "version": "1.0.0",
  "main": "dist-electron/main.js",
  "scripts": {
    "dev": "vite",
    "build": "vite build && electron-builder",
    "preview": "vite preview"
  },
  "build": {
    "appId": "com.example.my-electron-app",
    "productName": "My Electron App",
    "directories": {
      "output": "release"
    },
    "files": [
      "dist/**/*",
      "dist-electron/**/*"
    ],
    "win": {
      "target": [
        {
          "target": "nsis",
          "arch": ["x64", "ia32"]
        }
      ]
    },
    "mac": {
      "target": [
        {
          "target": "dmg",
          "arch": ["x64", "arm64"]
        }
      ]
    },
    "linux": {
      "target": ["AppImage", "deb"]
    }
  }
}

最佳实践

1. 安全最佳实践

• 启用上下文隔离：设置 contextIsolation: true
• 禁用 Node.js 集成：设置 nodeIntegration: false
• 使用预加载脚本：通过 contextBridge 安全暴露 API
• 验证 IPC 消息：对所有 IPC 消息进行验证和 sanitize
• 使用最新版本：定期更新 Electron 和依赖库

2. 性能优化

• 减少主进程负担：复杂计算放在渲染进程
• 优化渲染进程：使用 Vue 3 的性能优化特性
• 合理使用 Web Workers：处理 CPU 密集型任务
• 优化启动时间：延迟加载非必要资源
• 使用 nativeImage：优化图标和图片加载

3. 桌面应用特性

• 窗口管理：合理设计窗口大小、位置和行为
• 菜单和快捷键：提供原生菜单和键盘快捷键
• 托盘应用：支持最小化到系统托盘
• 文件关联：支持打开应用关联的文件类型
• 通知：使用系统通知功能

4. 开发工作流

• 热更新：配置 Vite 热更新支持
• DevTools：开发时自动打开 DevTools
• 调试：使用 VS Code 调试主进程和渲染进程
• 日志：实现良好的日志记录机制
• 测试：集成自动化测试

5. 跨平台兼容性

• 使用跨平台 API：避免使用平台特定的 API
• 测试不同平台：在 Windows、macOS 和 Linux 上测试
• 处理平台差异：使用 process.platform 处理平台特定逻辑
• 遵循平台设计指南：符合各平台的设计规范

常见问题与解决方案

1. 问题：Vue 应用无法访问 Electron API

解决方案：确保：

• 预加载脚本正确配置了 contextBridge
• 在主进程中启用了 contextIsolation
• Vue 组件中检查 window.electronAPI 是否存在
• 预加载脚本路径配置正确

2. 问题：热更新不生效

解决方案：

• 确保 Vite 配置正确
• 检查主进程是否加载了正确的开发服务器 URL
• 重启开发服务器
• 检查网络连接

3. 问题：打包后应用无法运行

解决方案：

• 检查 package.json 中的 main 字段路径
• 确保打包配置包含了所有必要文件
• 检查控制台错误日志
• 验证 Electron 版本兼容性

4. 问题：应用启动时间过长

解决方案：

• 优化主进程代码
• 延迟加载非必要模块
• 减少渲染进程初始加载资源
• 使用 ready-to-show 事件优化窗口显示

5. 问题：跨平台样式不一致

解决方案：

• 使用 CSS 重置或 normalize
• 避免使用平台特定的样式
• 使用相对单位和弹性布局
• 测试不同平台的显示效果

6. 问题：IPC 通信失败

解决方案：

• 检查 IPC 通道名称是否一致
• 确保预加载脚本正确暴露了 API
• 检查主进程是否正确监听了事件
• 使用 invoke/handle 替代 send/on 进行异步通信

进一步学习资源

1. 官方文档

   • Electron 官方文档
   • Vite 官方文档
   • Vue 3 官方文档

2. 项目模板

   • vite-electron-builder - 成熟的 Vite + Electron 模板
   • electron-vue-vite - 官方 Electron + Vite 模板

3. 学习资源

   • Electron in Action - 书籍
   • Vue 3 + Electron 教程
   • Electron 中文文档

4. 社区资源

   • Electron 中文社区
   • Vue 中文社区
   • Electron Discord

5. 工具库

   • electron-store - 持久化存储
   • electron-log - 日志记录
   • electron-updater - 自动更新
   • electron-settings - 设置管理

课后练习

练习 1：创建基础 Electron 应用

• 使用 Vite + Vue 3 + Electron 模板创建项目
• 配置主进程和预加载脚本
• 实现基本的窗口管理
• 运行和测试应用

练习 2：实现 IPC 通信

• 在主进程和渲染进程之间实现双向 IPC 通信
• 实现计数器功能，通过 IPC 更新
• 添加事件监听和移除逻辑

练习 3：集成原生功能

• 实现文件对话框功能
• 添加系统通知
• 实现托盘应用
• 添加自定义菜单

练习 4：优化应用性能

• 实现应用启动优化
• 添加热更新支持
• 优化渲染性能
• 实现代码拆分

练习 5：打包和分发

• 配置 electron-builder
• 打包应用到不同平台
• 实现自动更新功能
• 测试打包后的应用

练习 6：实现复杂功能

• 创建多窗口应用
• 实现文件拖放功能
• 添加快捷键支持
• 实现应用状态持久化

通过以上练习，你将掌握 Vue 3 与 Electron 开发桌面应用的核心技能，能够构建功能完整、性能优良的跨平台桌面应用。