Electron&OpenHarmony 跨平台实战开发（一）：electron-vite 与 Vue3 架构搭建指南

前言

Electron 本身提供了完善的桌面能力，但如果希望在渲染层使用 Vue3 并保持高效的开发体验，electron-vite 是当前最易用的解决方案。本文整理从零初始化、交互式选项选择、项目结构到最终产出 HAP 的完整流程，帮助你快速复制可落地的架构。

为什么选择 electron-vite

对比项	Electron Forge + Webpack	electron-vite
构建速度	中等	极快（Vite 原生 ESM）
Vue3 支持	需手动配置 loader	模板内置
热更新体验	依赖 HMR 插件	默认即开
TypeScript	额外配置	模板可直接选择
产物拆分	需自定脚本	`electron-vite build` 自动输出 `main`/`preload`/`renderer`

环境准备

Node.js ≥ 18.17（建议 LTS）
包管理器任选：npm / pnpm / yarn
全局无需额外依赖，只需 npm create electron-vite@latest

交互式初始化（只需选择模板）

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

交互式选择：

? Project template: >> Vue (使用方向键选择，回车确认)

Vue
React
Vanilla

注意：

项目名称已在命令中指定，不会询问
包管理器根据调用命令自动检测（npm create → npm，pnpm create → pnpm）

如需使用 pnpm，请使用：pnpm create electron-vite@latest my-vue-electron-app

复制代码

cd my-vue-electron-app
npm install # 或 pnpm install（如果使用 pnpm create）
npm run dev # 或 pnpm dev

交互式选项详解

提示	作用	说明
Project template	决定渲染进程模板	`Vue`（快速）或 `Vue + TypeScript`（生产）注意：只有模板选择会交互式询问
项目名称	目录 + `package.json` 名称	已在命令中指定，不会询问
包管理器	配套锁文件与命令	根据调用命令自动检测： - `npm create` → npm - `pnpm create` → pnpm - `yarn create` → yarn

项目结构速览（最新模板）

文件目录

复制代码

my-vue-electron-app/
├─ electron/               # Electron 主/预加载模块
│  ├─ main.ts              # 主进程入口
│  ├─ preload.ts           # 预加载脚本入口
│  └─ electron-env.d.ts    # 类型声明
├─ src/                    # Vue3（Vite）渲染层
│  ├─ main.ts
│  ├─ App.vue
│  ├─ components/
│  ├─ assets/
│  └─ style.css
├─ index.html              # 渲染层 HTML 模板
├─ vite.config.ts          # Vite + Electron 联合配置
├─ electron-builder.json5  # 可选：electron-builder 打包配置
├─ package.json
└─ tsconfig*.json

配置文件要点

vite.config.ts：通过 defineConfig 同时配置主进程（build.rollupOptions.input = electron/main.ts）、预加载（electron/preload.ts）以及渲染层（默认 Vite 配置，可添加 vue() 插件、别名、代理等）。

package.json（模板示例）：

json 复制代码

{
  "main": "dist-electron/main/index.js",
  "scripts": {
    "dev": "vite dev",
    "build": "vite build && electron-builder",
    "preview": "vite build && electron ."
  }
}

实际脚本可能略有差异，但核心是 main 字段指向构建后的主进程入口。

electron-builder.json5：若需要生成安装包可启用；仅用于 HAP 集成时，可忽略该文件。
tsconfig.json / tsconfig.node.json：若选择 vue-ts 模板，已启用严格模式；可按需补充 paths、types 等。

常用扩展

需求	操作
引入 Vue Router	`pnpm add vue-router`，在 `renderer/src/main.ts` 注册
全局状态（Pinia）	`pnpm add pinia`，同样在 `renderer` 入口挂载
UI 组件库	建议使用支持 Vite 的库，如 Element Plus、Naive UI
环境变量	新建 `.env`, `.env.production`，通过 `import.meta.env` 访问

如何打包与产物

bash 复制代码

pnpm build
# 输出:
# dist/                 ← 渲染层（供 WebView/WebEngine 使用）
# dist-electron/
# ├─ main/              ← 主进程 bundle
# └─ preload/           ← 预加载 bundle

dist 等价于传统 Electron resources/app 中的前端资源。
dist-electron/main、dist-electron/preload 分别对应主进程与预加载脚本，可直接复制到鸿蒙 web_engine 模块。
若借助 electron-builder 继续打包桌面安装包，会在 dist/ 下生成 .exe/.dmg 等，与 HAP 集成无关，可忽略。

嵌入 OpenHarmony HAP 的建议流程

PC 端自测 ：使用 pnpm dev / pnpm build 确认 Electron 功能正常。
复制产物 ：
- 将 dist、dist-electron/main、dist-electron/preload 内的文件合并至 ohos_electron_hap/web_engine/src/main/resources/resfile/resources/app/。
- 保留 package.json，确保 main 字段指向复制后的主进程脚本（如 main/index.js）。
- 若启用了 asar，需先解包再拷贝。
DevEco Studio 构建 HAP ：在鸿蒙工程中执行 Build Hap(s)，得到 electron-*-signed.hap，随后完成签名与安装。

调试技巧

pnpm dev 默认带来主进程 + 渲染层热更新；可在 electron/main.ts 中设置 process.env.ELECTRON_DISABLE_SECURITY_WARNINGS = "true" 辅助调试。
pnpm build && pnpm preview 可在 Electron 外壳中加载 dist 资源，复制到 HAP 前先做回归测试。
若需精细控制依赖打包方式，可在 vite.config.ts 的 build.rollupOptions 中指定 external、plugins 等；逻辑与旧版 forge.config.js 一致。

总结

最新模板将主/预加载脚本集中在 electron/ 目录，渲染层沿用 Vite 默认的 src/；看似与旧文档不同，但职责划分完全一致。
pnpm build 产出的 dist + dist-electron 与传统 Electron resources/app 等价，可直接复制到 web_engine/src/main/resources/resfile/resources/app/。
迁移到鸿蒙时，确保 package.json 的 main 指向正确入口并按 DevEco Studio 流程生成 HAP，即可完成 Electron → OpenHarmony 的适配。