Electron 企业级桌面应用架构方案

本文档详细介绍了基于 electron-vite 框架，结合 React 与 TypeScript 的企业级桌面应用架构方案。重点涵盖了进程间通信 (IPC)、后端服务集成、数据库管理以及与 Web 端共享技术栈的最佳实践。

一、 核心基础技术栈

二、 项目目录结构

采用 electron-vite 标准结构，清晰划分主进程 (Main)、渲染进程 (Renderer) 与预加载脚本 (Preload)。

.
├── src/
│   ├── main/           # 主进程代码 (Node.js 环境)
│   │   ├── services/   # 后端服务层 (数据库、文件系统等)
│   │   ├── ipc/        # IPC 监听注册中心
│   │   └── index.ts    # 主进程入口
│   ├── preload/        # 预加载脚本 (桥接主进程与渲染进程)
│   │   └── index.ts
│   └── renderer/       # 渲染进程代码 (React + Vite)
│       ├── src/        # 参考 React 企业级架构 (components, hooks, service)
│       └── index.html
├── electron-vite.config.ts
└── package.json

三、 核心功能实现

3.1 安全的 IPC 通信模式

严禁在渲染进程直接开启 nodeIntegration。推荐使用 contextBridge 暴露受限的 API。

1. 预加载脚本 (Preload)

// src/preload/index.ts
import { contextBridge, ipcRenderer } from 'electron'
 
contextBridge.exposeInMainWorld('electronAPI', {
  // 渲染进程 -> 主进程 (Invoke/Handle 模式，支持异步返回)
  fetchData: (params: any) => ipcRenderer.invoke('db:fetch-data', params),
  
  // 主进程 -> 渲染进程 (监听模式)
  onUpdateStatus: (callback: (status: string) => void) => 
    ipcRenderer.on('status-updated', (_event, value) => callback(value))
})

2. 主进程监听 (Main)

// src/main/ipc/index.ts
import { ipcMain } from 'electron'
import { databaseService } from '../services/database'
 
export function registerIpcHandlers() {
  ipcMain.handle('db:fetch-data', async (_event, params) => {
    return await databaseService.query(params)
  })
}

3.2 后端服务与数据库集成

Electron 应用通常需要处理复杂的本地逻辑，建议在主进程中封装 Service 层。

1. 数据库服务 (SQLite)

推荐使用 better-sqlite3，性能优异且支持同步/异步操作。

• 初始化: 在应用启动时检查数据库文件并执行迁移。
• ORM: 可配合 Prisma 或 TypeORM 提升开发效率。

2. 外部后端服务集成

如果应用需要运行独立的后端服务（如 Go/Python 二进制文件）：

• 使用 child_process.spawn 启动服务。
• 通过 IPC 将服务状态同步至 UI。
• 确保在应用退出时正确关闭子进程。

四、 渲染进程技术方案 (React)

渲染进程的技术栈应与 React 企业级架构 保持高度一致，以降低迁移成本。

• UI 组件库: Ant Design (配合 ConfigProvider 配置)。
• 状态管理: Zustand (轻量级，适合桌面应用状态)。
• 数据流: 封装 useRequest 钩子，将 IPC 调用封装为类似 API 的调用。
• 样式: Tailwind CSS (原子化布局)。

五、 生产环境优化与打包

• 多环境配置: 使用 .env 区分开发与生产环境的 API 地址或数据库路径。
• 原生模块编译: 针对 SQLite 等原生模块，确保 electron-builder 配置正确。
• 自动更新: 集成 electron-updater 实现丝滑的增量更新体验。
• 代码混淆: 生产环境下对主进程代码进行混淆，保护业务逻辑。

六、 最佳实践建议

1. 单一职责: 主进程负责系统交互与数据处理，渲染进程仅负责 UI 展示。
2. 错误处理: 建立全局 IPC 错误拦截机制，防止主进程崩溃导致应用闪退。
3. 性能监控: 关注渲染进程的内存占用，避免在大数据量场景下出现卡顿。
4. 窗口管理: 封装统一的窗口创建工具类，管理多窗口生命周期。

最后更新: 2026年4月