📦 实战评估：Project Toolkit/桌面与跨平台UI/Electron

Electron 架构设计

Electron 是基于 Chromium + Node.js 的跨平台桌面应用框架，用 Web 技术（HTML/CSS/JS）构建原生桌面应用。

🏗️ 整体架构

┌─────────────────────────────────────────────────────┐
│                  Electron 应用                        │
│                                                      │
│  ┌────────────────────────────────────────────────┐  │
│  │              Main Process (Node.js)             │  │
│  │                                                 │  │
│  │  ┌──────────┐ ┌──────────┐ ┌───────────────┐   │  │
│  │  │   app    │ │ Browser  │ │   ipcMain     │   │  │
│  │  │ 生命周期  │ │ Window   │ │  消息处理      │   │  │
│  │  │          │ │ 窗口管理  │ │               │   │  │
│  │  └──────────┘ └──────────┘ └───────┬───────┘   │  │
│  │                                    │            │  │
│  └────────────────────────────────────┼────────────┘  │
│                                       │               │
│                    ┌──────────────────┼────────┐      │
│                    │    Preload Script│        │      │
│                    │  contextBridge   │        │      │
│                    │  (安全桥接层)      │        │      │
│                    └────────┬─────────┘        │      │
│                             │                   │      │
│  ┌──────────────────────────▼───────────────────┐     │
│  │           Renderer Process (Chromium)         │     │
│  │                                               │     │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │     │
│  │  │  HTML   │ │  CSS    │ │   JavaScript    │ │     │
│  │  │  DOM    │ │ Styles  │ │   Web APIs      │ │     │
│  │  └─────────┘ └─────────┘ └─────────────────┘ │     │
│  │                                               │     │
│  └───────────────────────────────────────────────┘     │
│                                                        │
└────────────────────────────────────────────────────────┘

🔑 核心设计思想

1. 继承 Chromium 的多进程模型

Electron 直接继承了 Chrome 浏览器的多进程架构：

设计哲学：每个窗口一个独立进程，一个窗口崩溃不影响其他窗口。这直接复用了 Chromium 成熟的进程隔离方案。

代价：每个窗口都运行一个完整的 Chromium 实例，内存开销大。

2. Node.js + Chromium 双引擎捆绑

每个 Electron 应用 = Chromium（渲染引擎）+ Node.js（后端运行时）

权衡：应用体积 100-200MB（每个应用都带一份 Chromium），但换来的是渲染一致性 — 同一应用在 Windows/macOS/Linux 上看起来完全一样。

3. 三层进程安全模型

信任级别:  高 ──────────────────────────────────── 低

Main Process          Preload Script          Renderer Process
(Node.js)             (Isolated World)        (Chromium 沙箱)
完全信任               部分信任                 不信任
可访问所有              contextBridge           只能通过暴露的
系统 API               安全暴露 API             API 通信

安全边界：

• Main Process：完全信任，可访问所有系统资源
• Preload Script：可访问 Node.js API，但通过 contextBridge 选择性暴露给 Renderer
• Renderer Process：运行不可信的 Web 代码，无 Node.js 访问权限

4. IPC 消息传递模型

Main Process 和 Renderer Process 不能直接通信，必须通过 IPC（Inter-Process Communication）：

Renderer Process                    Main Process
     │                                  │
     │  ipcRenderer.invoke('channel')   │
     │ ───────────────────────────────> │
     │                                  │  ipcMain.handle('channel')
     │                                  │  执行操作
     │  Promise<result>                 │
     │ <─────────────────────────────── │
     │                                  │
     │  ipcRenderer.send('channel')     │
     │ ───────────────────────────────> │  (单向，无返回值)
     │                                  │
     │  webContents.send('channel')     │
     │ <─────────────────────────────── │  (Main → Renderer)

🧩 核心组件

Main Process 模块

Renderer Process 模块

Preload Script

Preload 是连接 Main 和 Renderer 的安全桥梁：

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

// 暴露安全的 API 给 Renderer
contextBridge.exposeInMainWorld('electronAPI', {
  // 方法一：invoke（请求-响应）
  getVersion: () => ipcRenderer.invoke('get-version'),

  // 方法二：send + on（事件）
  onUpdateReady: (callback) => {
    ipcRenderer.on('update-ready', (_event, data) => callback(data));
  },

  // 方法三：暴露只读数据
  platform: process.platform,
  isDev: !app.isPackaged
});

关键安全规则：

• 永远不要暴露 ipcRenderer 本身给 Renderer
• 永远不要暴露 require、fs、child_process 等原始 API
• 只暴露最小必要的功能

🔄 IPC 通信详解

invoke / handle（推荐，请求-响应）

// Main Process
const { ipcMain } = require('electron');

ipcMain.handle('read-file', async (_event, filePath) => {
  const content = await fs.promises.readFile(filePath, 'utf-8');
  return content;
});

// Renderer Process (通过 Preload 暴露)
const content = await window.electronAPI.readFile('/path/to/file');

send / on（单向，Renderer → Main）

// Main Process
ipcMain.on('open-settings', (_event) => {
  createSettingsWindow();
});

// Renderer Process
window.electronAPI.openSettings();

webContents.send（单向，Main → Renderer）

// Main Process
mainWindow.webContents.send('download-progress', { percent: 75 });

// Renderer Process (通过 Preload 监听)
window.electronAPI.onDownloadProgress((data) => {
  progressBar.style.width = `${data.percent}%`;
});

📐 进程模型详解

窗口进程隔离

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   Main Process  │  │  Renderer #1    │  │  Renderer #2    │
│   (1个，共享)    │  │  (窗口A)        │  │  (窗口B)         │
│                 │  │  独立进程        │  │  独立进程        │
│  app            │  │  HTML/CSS/JS    │  │  HTML/CSS/JS    │
│  BrowserWindow  │  │  Preload        │  │  Preload        │
│  ipcMain        │  │  ipcRenderer    │  │  ipcRenderer    │
└─────────────────┘  └─────────────────┘  └─────────────────┘

• Main Process 始终只有 1 个
• 每个 BrowserWindow 有独立的 Renderer Process
• 窗口间通信必须经过 Main Process 中转

Utility Process

Electron v24+ 引入的 Node.js 子进程，用于 CPU 密集型任务：

const { utilityProcess } = require('electron');

const child = utilityProcess.fork('worker.js');
child.postMessage({ task: 'heavy-computation' });
child.on('message', (result) => {
  console.log('Result:', result);
});

🛡️ 安全架构

安全最佳实践（20 条规则）

Context Isolation（上下文隔离）

┌──────────────────────────────────────────┐
│           Renderer Process               │
│                                          │
│  ┌────────────────┐  ┌────────────────┐  │
│  │  Main World    │  │  Isolated World│  │
│  │  (网页代码)    │  │  (Preload)     │  │
│  │                │  │                │  │
│  │  window.electronAPI  ← contextBridge  │
│  │  (只能调用暴露的API)  (可访问Node.js)│  │
│  │                │  │                │  │
│  │  ✗ require     │  │  ✓ require     │  │
│  │  ✗ fs          │  │  ✓ fs          │  │
│  │  ✗ child_process│  │  ✓ child_process│ │
│  └────────────────┘  └────────────────┘  │
└──────────────────────────────────────────┘

🔧 打包与分发

electron-builder vs Electron Forge

支持的打包格式

自动更新机制

┌──────────┐     ┌──────────────┐     ┌──────────┐
│ 用户设备 │     │ 更新服务器    │     │ 发布渠道  │
│          │     │ (GitHub/S3)  │     │          │
│ 启动应用 │ ──> │ 检查版本     │ <── │ 推送新版本│
│          │     │              │     │          │
│ 下载更新 │ <── │ 返回更新信息 │     │          │
│          │     │              │     │          │
│ 重启应用 │     │              │     │          │
└──────────┘     └──────────────┘     └──────────┘

🆚 与 Tauri 架构对比

🔗 相关链接

• JavaScript Node.js Chromium 跨平台开发 桌面应用 Tauri
• Electron 官方文档
• 进程模型
• 安全指南
• electron-builder
• Electron Forge

📝 个人备注

（留白，供后续补充学习心得）