欢迎加入开源鸿蒙PC社区：https://harmonypc.csdn.net/

前言

Electron + Vue3 是开发跨平台桌面应用的优秀组合。本文基于 electron-vite 脚手架，详细介绍如何从零搭建一个完整的 Electron + Vue3 项目架构，包括项目创建、目录结构、配置文件、依赖集成等核心内容。

一、项目创建

1.1 使用 electron-vite 创建项目

electron-vite 是目前最推荐的 Electron + Vue3 项目脚手架，提供了开箱即用的配置和优秀的开发体验。

npm create electron-vite@latest my-vue-electron-desk

执行命令后，选择模板：

• Project template: 选择 Vue 或 Vue + TypeScript（推荐 TypeScript）
• Package name: 确认项目名称

1.2 安装依赖

cd my-vue-electron-desk
npm install

如果遇到 Electron 下载问题，可以配置镜像源（参考之前的文档）。

二、项目目录结构

创建完成后的标准目录结构如下：

my-vue-electron-desk/
├── electron/              # Electron 主进程代码
│   ├── main.ts           # 主进程入口
│   ├── preload.ts        # 预加载脚本
│   └── electron-env.d.ts # Electron 类型声明
├── src/                  # Vue3 渲染进程代码
│   ├── components/       # Vue 组件
│   ├── views/            # 页面组件
│   ├── stores/           # Pinia 状态管理
│   ├── router/           # Vue Router 路由
│   ├── utils/            # 工具函数
│   ├── types/            # TypeScript 类型定义
│   ├── composables/      # 组合式函数
│   ├── App.vue           # 根组件
│   └── main.ts           # 渲染进程入口
├── public/               # 静态资源
├── package.json          # 项目配置
├── vite.config.ts        # Vite 配置
├── tsconfig.json         # TypeScript 配置
└── index.html            # HTML 模板

2.1 关键目录说明

• electron/：主进程代码，负责窗口管理、系统 API 调用
• src/：渲染进程代码，运行 Vue3 应用
• src/stores/：Pinia 状态管理，替代 Vuex
• src/router/：Vue Router 路由配置
• src/types/：TypeScript 类型定义，提升代码质量

三、核心配置文件

3.1 vite.config.ts - Vite 构建配置

import { defineConfig } from "vite";
import path from "node:path";
import electron from "vite-plugin-electron/simple";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [
    vue(),
    electron({
      main: {
        entry: "electron/main.ts",  // 主进程入口
      },
      preload: {
        input: path.join(__dirname, "electron/preload.ts"),  // 预加载脚本
      },
      renderer: {},
    }),
  ],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "src"),  // 路径别名
    },
  },
});

关键配置说明：

• electron 插件：配置主进程和预加载脚本
• resolve.alias：配置 @ 别名，方便导入文件

3.2 tsconfig.json - TypeScript 配置

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]  // 路径映射，配合 Vite 别名
    }
  },
  "include": ["src/**/*.ts", "src/**/*.vue", "electron"]
}

关键配置说明：

• strict: true：启用严格模式，提升类型安全
• paths：配置路径映射，与 Vite 别名保持一致

3.3 package.json - 项目依赖

{
  "dependencies": {
    "vue": "^3.4.21",
    "pinia": "^3.0.4",
    "vue-router": "^4.6.3"
  },
  "devDependencies": {
    "electron": "^30.0.1",
    "vite": "^5.1.6",
    "typescript": "^5.2.2",
    "vite-plugin-electron": "^0.28.6"
  }
}

四、依赖集成

4.1 安装 Pinia 和 Vue Router

npm install pinia vue-router

4.2 创建 Pinia 实例

src/stores/index.ts：

import { createPinia } from "pinia";

const pinia = createPinia();

export default pinia;

4.3 创建 Vue Router 配置

src/router/index.ts：

import { createRouter, createWebHashHistory } from "vue-router";
import type { RouteRecordRaw } from "vue-router";

const routes: RouteRecordRaw[] = [
  {
    path: "/",
    name: "Home",
    component: () => import("@/views/Home.vue"),
  },
  {
    path: "/about",
    name: "About",
    component: () => import("@/views/About.vue"),
  },
];

const router = createRouter({
  history: createWebHashHistory(),  // Electron 中使用 hash 模式
  routes,
});

export default router;

注意：Electron 应用推荐使用 createWebHashHistory，避免路径问题。

4.4 在 main.ts 中集成

src/main.ts：

import { createApp } from "vue";
import App from "./App.vue";
import pinia from "@/stores";
import router from "@/router";

const app = createApp(App);

app.use(pinia);   // 注册 Pinia
app.use(router);  // 注册 Vue Router

app.mount("#app");

4.5 在 App.vue 中使用路由

src/App.vue：

<template>
  <div id="app">
    <nav>
      <router-link to="/">Home</router-link>
      <router-link to="/about">About</router-link>
    </nav>
    <router-view />
  </div>
</template>

五、TypeScript 类型声明

5.1 Vue 组件类型声明

src/vite-env.d.ts：

/// <reference types="vite/client" />

declare module "*.vue" {
  import type { DefineComponent } from "vue";
  const component: DefineComponent<{}, {}, any>;
  export default component;
}

这个声明让 TypeScript 能够识别 .vue 文件的导入。

5.2 Electron API 类型扩展

src/types/index.ts：

declare global {
  interface Window {
    electronAPI?: {
      // 后续会在这里添加 Electron API 类型
    };
  }
}

export {};

六、验证项目架构

6.1 运行项目

npm run dev

如果一切正常，应该看到：

• Electron 窗口打开
• Vue3 应用正常渲染
• 路由导航正常工作

6.2 检查清单

• 项目能够正常启动
• 路由导航功能正常
• Pinia 可以正常使用
• TypeScript 类型检查通过
• 路径别名 @ 正常工作

📸 截图位置5：请截图显示 Electron 应用运行效果，包含导航栏和页面内容

七、项目架构优势

通过以上配置，我们获得了一个：

1. 类型安全：TypeScript 严格模式，减少运行时错误
2. 开发高效：Vite 热更新，开发体验优秀
3. 结构清晰：目录组织合理，易于维护
4. 扩展性强：支持 Pinia、Vue Router 等生态
5. 跨平台：基于 Electron，支持 Windows/Mac/Linux

总结

本文介绍了 Electron + Vue3 项目的完整架构搭建过程，包括：

1. ✅ 使用 electron-vite 创建项目
2. ✅ 配置标准目录结构
3. ✅ 集成 Pinia 状态管理
4. ✅ 集成 Vue Router 路由
5. ✅ 配置 TypeScript 类型系统
6. ✅ 设置路径别名

完成以上步骤后，你就拥有了一个功能完整、结构清晰的 Electron + Vue3 项目基础架构，可以在此基础上开发具体的业务功能。