Electron+Vite+Element Plus：从零搭建一个带路由和网络请求的桌面应用（保姆级教程）

Electron+Vite+Element Plus：从零搭建一个带路由和网络请求的桌面应用（保姆级教程）

在当今快速发展的前端生态中，Electron凭借其跨平台特性和强大的原生能力，成为构建桌面应用的首选方案。结合Vite的极速构建和Vue 3的响应式特性，再搭配Element Plus的丰富UI组件，可以快速打造出功能完善、体验优秀的桌面应用。本文将带你从零开始，一步步构建一个具备完整路由和网络请求功能的Electron应用。

1. 环境准备与项目初始化

在开始之前，确保你的开发环境满足以下要求：

• Node.js 16.x或更高版本
• npm 8.x或更高版本（或yarn 1.22+）
• 一个现代化的代码编辑器（如VSCode）

打开终端，执行以下命令创建项目：

npm create @quick-start/electron@latest

或者使用yarn：

yarn create @quick-start/electron

创建过程中，你会被询问一些配置选项：

1. 项目名称（保持默认或自定义）
2. 选择框架（选择Vue）
3. 是否添加TypeScript（建议选择是）
4. 是否安装依赖（选择是）

创建完成后，进入项目目录并启动开发服务器：

cd your-project-name npm run dev

此时，你应该能看到一个基本的Electron应用窗口弹出。这个初始项目已经配置好了Electron和Vite的基本集成，为我们后续的开发打下了良好基础。

2. 项目结构优化与清理

初始项目包含了一些我们可能不需要的示例文件和代码。让我们先进行一些清理工作：

1. 删除src/renderer/assets和src/renderer/components目录下的所有文件
2. 清理src/renderer/main.js中的样式引入
3. 清空App.vue文件，只保留基本结构

清理后的App.vue应该如下所示：

<template> <div>Hello Electron!</div> </template> <script setup> // 这里将添加我们的逻辑 </script> <style> /* 这里将添加我们的样式 */ </style>

运行项目确认一切正常后，我们就可以开始添加更多功能了。

3. 集成Element Plus UI库

Element Plus是一个基于Vue 3的组件库，提供了丰富的UI组件，非常适合快速构建企业级应用。

首先安装Element Plus：

npm install element-plus --save

然后在src/renderer/main.js中配置Element Plus：

import { createApp } from 'vue' import ElementPlus from 'element-plus' import 'element-plus/dist/index.css' import App from './App.vue' const app = createApp(App) app.use(ElementPlus) app.mount('#app')

现在，我们可以在App.vue中添加一个Element Plus按钮进行测试：

<template> <el-button type="primary">点击我</el-button> </template>

保存后，你应该能看到一个漂亮的蓝色按钮出现在窗口中，这表示Element Plus已经成功集成。

4. 配置Vue Router实现页面导航

对于任何稍复杂的应用，路由管理都是必不可少的。我们将使用Vue Router来实现多页面导航。

首先安装Vue Router：

npm install vue-router@4

创建基本的页面结构：

1. 在src/renderer/src下新建views文件夹
2. 在views中创建Home.vue和About.vue两个页面组件

Home.vue内容示例：

<template> <div class="home"> <h1>首页</h1> <p>这里是应用的主页面</p> </div> </template>

About.vue内容示例：

<template> <div class="about"> <h1>关于</h1> <p>这里是关于页面</p> </div> </template>

接下来，创建路由配置文件。在src/renderer/src下新建router文件夹，并在其中创建index.js：

import { createRouter, createWebHashHistory } from 'vue-router' import Home from '../views/Home.vue' import About from '../views/About.vue' const routes = [ { path: '/', redirect: '/home' }, { path: '/home', name: 'Home', component: Home }, { path: '/about', name: 'About', component: About } ] const router = createRouter({ history: createWebHashHistory(), routes }) export default router

注意：我们使用createWebHashHistory而不是createWebHistory，因为Electron应用通常以文件协议运行，hash模式更可靠。

最后，在main.js中注册路由：

import { createApp } from 'vue' import App from './App.vue' import ElementPlus from 'element-plus' import 'element-plus/dist/index.css' import router from './router' const app = createApp(App) app.use(ElementPlus) app.use(router) app.mount('#app')

5. 创建导航菜单组件

为了在应用中进行页面切换，我们需要创建一个导航菜单组件。在src/renderer/src/components下新建NavBar.vue：

<template> <el-menu :default-active="activeIndex" class="el-menu-demo" mode="horizontal" @select="handleSelect" > <el-menu-item index="/home">首页</el-menu-item> <el-menu-item index="/about">关于</el-menu-item> </el-menu> </template> <script setup> import { ref } from 'vue' import { useRouter } from 'vue-router' const router = useRouter() const activeIndex = ref('/home') const handleSelect = (key) => { router.push(key) } </script> <style> .el-menu-demo { margin-bottom: 20px; } </style>

然后修改App.vue来使用这个导航组件和路由视图：

<template> <NavBar /> <router-view /> </template> <script setup> import NavBar from './components/NavBar.vue' </script>

现在，你应该能看到一个顶部导航栏，点击不同的菜单项可以在首页和关于页面之间切换。

6. 实现网络请求功能

在Electron应用中处理网络请求有几种方式，我们将展示两种常见的方法：在主进程中使用axios和在渲染进程中使用axios。

方法一：在主进程中处理请求

这种方法更安全，因为主进程不受同源策略限制。

首先安装axios：

npm install axios

然后修改主进程代码（通常位于src/main/index.js）：

import axios from 'axios' // 在app.whenReady()中添加IPC监听 ipcMain.on('fetch-posts', async (event) => { try { const response = await axios.get('https://jsonplaceholder.typicode.com/posts') event.sender.send('posts-data', response.data) } catch (error) { console.error('请求失败:', error) event.sender.send('posts-data', []) } })

在预加载脚本（src/preload/index.js）中暴露API：

contextBridge.exposeInMainWorld('electronAPI', { fetchPosts: () => ipcRenderer.send('fetch-posts'), onPostsData: (callback) => ipcRenderer.on('posts-data', callback) })

最后，在Home.vue中使用这个API：

<template> <div> <el-button type="primary" @click="fetchPosts">获取文章</el-button> <el-table :data="posts" style="width: 100%"> <el-table-column prop="id" label="ID" width="80" /> <el-table-column prop="title" label="标题" /> </el-table> </div> </template> <script setup> import { ref } from 'vue' const posts = ref([]) const fetchPosts = () => { window.electronAPI.fetchPosts() window.electronAPI.onPostsData((event, data) => { posts.value = data }) } </script>

方法二：在渲染进程中直接请求

如果你确定请求的API支持CORS或者你已配置好CSP，也可以在渲染进程中直接使用axios。

首先在src/renderer/src下创建api文件夹，然后创建posts.js：

import axios from 'axios' export const getPosts = () => { return axios.get('https://jsonplaceholder.typicode.com/posts') }

然后在Home.vue中使用：

<template> <div> <el-button type="primary" @click="fetchPosts">获取文章</el-button> <el-table :data="posts" style="width: 100%"> <el-table-column prop="id" label="ID" width="80" /> <el-table-column prop="title" label="标题" /> </el-table> </div> </template> <script setup> import { ref } from 'vue' import { getPosts } from '../api/posts' import { ElMessage } from 'element-plus' const posts = ref([]) const fetchPosts = async () => { try { const response = await getPosts() posts.value = response.data ElMessage.success('数据加载成功') } catch (error) { console.error(error) ElMessage.error('数据加载失败') } } </script>

注意：如果遇到跨域问题，需要在index.html中修改CSP策略，添加connect-src规则。

7. 应用打包与优化

开发完成后，我们需要将应用打包成可执行文件。Electron Forge是一个流行的打包工具，我们的项目已经集成了它。

运行以下命令进行打包：

npm run make

打包完成后，你可以在out文件夹中找到生成的可执行文件。

为了优化应用性能，可以考虑以下几点：

1. 代码分割：利用Vite的动态导入功能分割代码
2. 预加载优化：合理使用Electron的preload脚本
3. 生产环境配置：区分开发和生产环境配置
4. 打包配置：调整Electron Forge的打包选项

在forge.config.js中，你可以自定义打包选项：

module.exports = { packagerConfig: { asar: true, icon: 'resources/icon' // 无扩展名的图标文件 }, makers: [ { name: '@electron-forge/maker-squirrel', config: { name: 'your_app_name' } }, { name: '@electron-forge/maker-zip', platforms: ['darwin'] }, { name: '@electron-forge/maker-deb', config: {} }, { name: '@electron-forge/maker-rpm', config: {} } ] }

8. 进阶功能与扩展

完成基础功能后，你可以考虑添加以下进阶功能：

1. 状态管理：集成Pinia进行全局状态管理
2. 本地存储：使用electron-store管理应用配置
3. 系统集成：实现文件系统操作、系统通知等原生功能
4. 自动更新：配置应用自动更新机制
5. 多窗口管理：实现多窗口应用架构

例如，添加Pinia进行状态管理：

首先安装Pinia：

npm install pinia

然后在main.js中配置：

import { createApp } from 'vue' import { createPinia } from 'pinia' import App from './App.vue' const app = createApp(App) app.use(createPinia()) app.mount('#app')

创建一个store：

// stores/counter.js import { defineStore } from 'pinia' export const useCounterStore = defineStore('counter', { state: () => ({ count: 0 }), actions: { increment() { this.count++ } } })

在组件中使用：

<template> <div> <p>计数: {{ counter.count }}</p> <el-button @click="counter.increment()">增加</el-button> </div> </template> <script setup> import { useCounterStore } from '../stores/counter' const counter = useCounterStore() </script>

9. 调试与错误处理

在开发过程中，有效的调试和错误处理至关重要。

主进程调试：

• 使用VS Code的调试配置
• 在代码中添加console.log语句
• 使用electron-debug工具

渲染进程调试：

• 使用Chrome开发者工具（默认快捷键Ctrl+Shift+I）
• 集成Vue Devtools

错误处理最佳实践：

1. 在主进程和渲染进程中都添加全局错误处理器
2. 使用try-catch处理异步操作
3. 为用户提供友好的错误提示

示例全局错误处理器：

// 在主进程中 process.on('uncaughtException', (error) => { console.error('未捕获的异常:', error) }) // 在渲染进程中 window.addEventListener('error', (event) => { console.error('渲染进程错误:', event.error) ElMessage.error('发生了一个意外错误') })

10. 性能优化技巧

为了确保应用运行流畅，可以考虑以下优化措施：

1. 懒加载路由组件：

const routes = [ { path: '/about', component: () => import('../views/About.vue') } ]

2. 使用Vite的优势：

• 配置vite.config.js优化构建
• 利用Vite的HMR快速开发

3. Electron性能优化：

const win = new BrowserWindow({ webPreferences: { nodeIntegration: false, contextIsolation: true, sandbox: true, webSecurity: true } })

4. 减少主进程负载：

• 将计算密集型任务移到Worker线程
• 合理使用IPC通信

5. 资源优化：

• 压缩图片和其他静态资源
• 使用适当的缓存策略

11. 安全最佳实践

Electron应用安全至关重要，以下是一些关键安全措施：

1. 启用上下文隔离：

new BrowserWindow({ webPreferences: { contextIsolation: true, preload: path.join(__dirname, 'preload.js') } })

2. 禁用Node.js集成：

webPreferences: { nodeIntegration: false }

3. 严格CSP策略：

<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' https://api.example.com;">

4. 验证所有用户输入：

• 特别是通过IPC传递的数据

5. 保持依赖更新：

• 定期运行npm audit检查安全漏洞
• 及时更新Electron和其他依赖

12. 跨平台考虑

Electron应用可以运行在Windows、macOS和Linux上，但需要注意一些平台差异：

1. 路径处理：

const path = require('path') const userDataPath = app.getPath('userData') const configPath = path.join(userDataPath, 'config.json')

2. 菜单差异：

• macOS应用菜单在顶部栏
• Windows/Linux菜单在窗口内

3. 快捷键：

• 考虑不同平台的快捷键习惯
• 使用process.platform进行平台检测

4. 打包配置：

• 为不同平台生成不同的图标
• 配置平台特定的打包选项

5. UI适配：

• 测试不同平台上的UI表现
• 考虑不同操作系统的设计语言

13. 实际项目经验分享

在真实项目开发中，有几个关键点值得注意：

1. 项目结构组织：

/src /main # 主进程代码 /renderer # 渲染进程代码 /assets /components /router /stores /views /utils /preload # 预加载脚本

2. 环境变量管理：

• 使用dotenv管理不同环境配置
• 在Vite中配置环境变量前缀VITE_

3. 代码规范：

• 配置ESLint和Prettier统一代码风格
• 使用Git钩子在提交前自动检查

4. 文档编写：

• 为项目添加README说明
• 记录项目配置和构建步骤
• 编写API文档（如有后端接口）

5. 持续集成：

• 配置GitHub Actions或类似CI工具
• 自动化测试和构建流程

14. 常见问题解决方案

在开发过程中，你可能会遇到以下问题：

1. 白屏问题：

• 检查预加载脚本是否正确配置
• 确认渲染进程入口文件路径正确

2. IPC通信失败：

• 确保在主进程和预加载脚本中正确注册了IPC通道
• 检查通道名称是否一致

3. 样式不生效：

• 检查CSS文件是否正确引入
• 确认样式选择器没有冲突

4. 打包后资源加载失败：

• 使用path.join(__dirname, '../assets/...')确保正确路径
• 检查打包配置中的资源处理

5. 性能瓶颈：

• 使用Chrome DevTools分析性能
• 优化频繁更新的组件
• 考虑虚拟滚动长列表

15. 测试策略

为确保应用质量，应该实施全面的测试：

1. 单元测试：

• 使用Vitest测试工具函数和组件逻辑
• 测试覆盖率至少达到80%

2. 组件测试：

• 使用Vue Test Utils测试组件行为
• 模拟用户交互和props变化

3. E2E测试：

• 使用Spectron或Cypress测试完整流程
• 覆盖主要用户场景

4. 主进程测试：

• 使用electron-mocha测试主进程逻辑
• 模拟IPC通信

5. 跨平台测试：

• 在实际设备上测试不同平台
• 使用CI工具自动化跨平台测试

16. 发布与分发

准备好发布应用时，考虑以下步骤：

1. 代码签名：

• 为Windows应用获取代码签名证书
• 为macOS应用配置开发者ID

2. 应用商店：

• 考虑发布到Microsoft Store或Mac App Store
• 遵循各商店的审核指南

3. 自动更新：

• 集成electron-updater
• 配置更新服务器或GitHub Releases

4. 版本管理：

• 遵循语义化版本控制(SemVer)
• 维护详细的变更日志

5. 用户反馈：

• 集成错误报告工具如Sentry
• 提供用户反馈渠道

17. 社区资源与学习

要进一步提升Electron开发技能，可以参考以下资源：

1. 官方文档：

• Electron文档
• Vite文档
• Vue 3文档

2. 开源项目：

• 研究优秀的Electron开源项目结构
• 学习社区最佳实践

3. 工具推荐：

• electron-builder：替代electron-forge的打包工具
• electron-devtools-installer：方便安装DevTools扩展

4. 社区支持：

• Electron官方Discord
• Stack Overflow的electron标签
• GitHub Discussions

5. 进阶主题：

• 原生模块集成
• 性能分析与优化
• 安全加固

18. 项目示例扩展

基于我们构建的基础应用，你可以进一步扩展功能：

1. 添加设置页面：

• 使用electron-store持久化用户配置
• 实现主题切换功能

2. 集成数据库：

• 使用SQLite进行本地数据存储
• 或连接远程数据库

3. 实现文件操作：

• 使用Electron的dialog模块打开/保存文件
• 结合fs模块处理文件内容

4. 添加系统托盘：

• 创建托盘图标和上下文菜单
• 实现后台运行功能

5. 通知系统：

• 使用系统原生通知
• 自定义通知样式和行为

19. 现代化Electron开发趋势

保持对Electron生态最新发展的关注：

1. Vite集成：

• 更快的开发和构建速度
• 更好的HMR体验

2. Web Components：

• 考虑使用Web Components增强跨框架兼容性

3. TypeScript全面采用：

• 主进程和渲染进程都使用TypeScript
• 严格的类型检查减少运行时错误

4. ES模块支持：

• Electron逐步增强对ESM的支持
• 考虑迁移到ES模块语法

5. 性能监控：

• 集成性能监控工具
• 实时跟踪应用性能指标

20. 从项目到产品

将技术原型转化为成熟产品需要考虑：

1. 用户体验优化：

• 进行用户测试收集反馈
• 优化交互流程和界面设计

2. 可访问性：

• 遵循WCAG标准
• 确保键盘导航和屏幕阅读器支持

3. 多语言支持：

• 使用i18n库实现国际化
• 管理翻译文件

4. 数据分析：

• 集成匿名使用统计
• 了解用户行为模式

5. 商业模式：

• 考虑免费增值模式
• 或企业授权方案

通过本教程，你已经掌握了使用Electron、Vite、Vue 3和Element Plus构建现代化桌面应用的全套技能。从项目初始化到路由配置，从网络请求到打包发布，我们覆盖了开发一个完整Electron应用所需的关键步骤。记住，真正的学习来自于实践，所以现在就开始构建你自己的Electron应用吧！