electron-best-practices

Electron + React 最佳实践

指导 AI Agent 使用 React 构建安全、可用于生产环境的 Electron 应用。本技能提供安全模式、类型安全的 IPC 通信、项目设置指南、打包与代码签名工作流，以及用于分析、脚手架搭建和类型生成的工具。

何时使用本技能

在以下情况下使用本技能：

• 生成 Electron 主进程、预加载进程或渲染进程代码
• 配置 electron-vite 或 Electron Forge
• 设置进程间的 IPC 通信
• 实施安全模式（contextBridge、sandbox、CSP）
• 打包、签名和公证桌面应用
• 使用 Playwright 测试 Electron 应用
• 设计多窗口架构

在以下情况下不要使用本技能：

• 构建 Tauri 应用（范式不同，请使用 Tauri 专用指南）
• 构建没有桌面端需求的纯 Web 应用
• 目标 Electron 版本低于 20（安全默认设置有所不同）
• 使用非 React 渲染器框架（请使用对应框架的专用技能）

核心原则

1. 安全优先的架构

现代 Electron 安全机制依赖三个在 Electron 20+ 中成为标准的默认设置：上下文隔离、沙箱模式和禁用 nodeIntegration。禁用其中任何一项都可能导致 XSS 攻击升级为完整的远程代码执行。所有主进程与渲染进程间的通信都必须通过 contextBridge：

// preload.ts - SECURE pattern
contextBridge.exposeInMainWorld('electronAPI', {
  loadPreferences: () => ipcRenderer.invoke('load-prefs'),
  saveFile: (content: string) => ipcRenderer.invoke('save-file', content),
  onUpdateCounter: (callback: (value: number) => void) => {
    const handler = (_event: IpcRendererEvent, value: number) => callback(value);
    ipcRenderer.on('update-counter', handler);
    return () => ipcRenderer.removeListener('update-counter', handler);
  }
});

对于加载本地文件的应用，请通过 HTTP 标头设置内容安全策略，将脚本来源限制为 'self'。

2. 类型安全的 IPC 通信

对于请求-响应通信，优先使用 invoke/handle 模式，而不是 send/on，这样可以提供正确的 async/await 语义和错误传播。对于类型化通道，请使用映射类型模式：

type IpcChannelMap = {
  'load-prefs': { args: []; return: UserPreferences };
  'save-file': { args: [content: string]; return: { success: boolean } };
};

对于复杂应用，electron-trpc 使用 tRPC 的路由器模式和 Zod 验证，提供完整的类型安全：

export const appRouter = t.router({
  greeting: t.procedure
    .input(z.object({ name: z.string() }))
    .query(({ input }) => `Hello, ${input.name}!`),
});

处理跨 IPC 边界的错误时需要格外注意，因为 Electron 只会序列化 Error 对象的 message 属性。请将响应封装为 { success, data, error } 结果类型，以保留完整的错误上下文。

3. 现代项目设置

推荐的技术栈使用 electron-vite 进行开发，并使用 Electron Forge 进行打包。electron-vite 提供统一配置来管理主进程、预加载进程和渲染进程，并支持亚秒级开发服务器启动和即时 HMR。Electron Forge 使用 Electron 官方一方软件包进行签名和公证。

src/
├── main/           # Main process (Node.js environment)
│   ├── index.ts
│   └── ipc/        # IPC handlers
├── preload/        # Secure bridge via contextBridge
│   ├── index.ts
│   └── index.d.ts  # TypeScript declarations for exposed APIs
└── renderer/       # React application (pure web, no Node access)
    ├── src/
    └── index.html

4. React 集成模式

React 18 的并发特性可以在基于 Electron Chromium 的渲染器中正常运行。Strict Mode 对 effect 的双重调用可以捕获 IPC 监听器泄漏，否则这类问题可能导致内存问题。注册 IPC 监听器的 effect 始终应返回清理函数：

useEffect(() => {
  const cleanup = window.electronAPI.onUpdateCounter((value) => {
    setCount(value);
  });
  return cleanup;
}, []);

对于多窗口应用，主进程应作为共享状态的唯一真实来源。使用 electron-store 进行持久化，并结合 IPC 广播，使任一窗口中的变更都能更新其他所有窗口。

快速参考

类别	首选方案	避免使用
安全	contextBridge.exposeInMainWorld()	nodeIntegration: true
IPC	invoke/handle 模式	将 send/on 用于请求-响应
预加载	类型化函数封装	暴露原始 ipcRenderer
构建工具	electron-vite	基于 webpack 的工具链
打包	Electron Forge	手动打包
状态	Zustand + electron-store	简单应用中使用 Redux
测试	Playwright E2E	Spectron（已弃用）
更新	electron-updater	手动检查更新
签名	集成到 CI 的代码签名	未签名的发行版本
CSP	HTTP 标头，仅允许 'self'	不设置 CSP
错误处理	结果类型 {success, data, error}	在 IPC 中直接传递 Error
多窗口	以主进程作为状态中心	窗口间直接通信

代码生成指南

生成 Electron 代码时，请遵循以下模式：

BrowserWindow 创建

const win = new BrowserWindow({
  webPreferences: {
    preload: path.join(__dirname, '../preload/index.js'),
    contextIsolation: true,
    sandbox: true,
    nodeIntegration: false,
  },
});

始终启用 contextIsolation 和 sandbox。绝不启用 nodeIntegration。preload 路径必须解析到构建输出位置。

IPC 处理程序模块

export function registerFileHandlers(): void {
  ipcMain.handle('save-file', async (_event, content: string) => {
    try {
      await fs.writeFile(filePath, content);
      return { success: true, data: filePath };
    } catch (err) {
      return { success: false, error: (err as Error).message };
    }
  });
}

将相关处理程序归入模块。所有返回值都使用 Result 类型模式。验证从渲染进程接收的所有参数。

常见反模式

生成 Electron 代码时，请避免以下模式：

反模式	问题	解决方案
nodeIntegration: true	XSS 会升级为完整的 RCE	保持禁用（默认）
直接暴露 ipcRenderer	渲染进程获得完整的 IPC 访问权限	通过 contextBridge 函数封装
缺少 contextIsolation	渲染进程可访问 preload 作用域	保持启用（从 Electron 12 起默认启用）
未进行代码签名	操作系统安全警告，Gatekeeper 会拦截	为所有平台签名并进行公证
BrowserWindow 未启用 sandbox	preload 拥有完整的 Node.js 访问权限	启用 sandbox（从 Electron 20 起默认启用）
未验证 IPC 参数	来自渲染进程的注入攻击	使用 Zod 或手动检查进行验证
服务器绑定到 0.0.0.0	本地服务器暴露到网络	始终绑定到 127.0.0.1
缺少 CSP 标头	脚本注入途径	通过 HTTP 标头设置严格的 CSP
未序列化 IPC 错误	跨边界传递时丢失错误上下文	使用 Result 类型模式
使用 Spectron 进行测试	已弃用，最高支持 Electron 13	使用 Playwright

完整的安全审计清单请参阅 references/security/security-checklist.md。

脚本参考

analyze-security.ts

分析 Electron 项目的安全配置错误：

deno run --allow-read scripts/analyze-security.ts <path> [options]

Options:
  --strict    Enable all checks
  --json      Output JSON for CI
  -h, --help  Show help

Examples:
  # Analyze a project
  deno run --allow-read scripts/analyze-security.ts ./src

  # Strict mode for CI pipeline
  deno run --allow-read scripts/analyze-security.ts ./src --strict --json

scaffold-electron-app.ts

使用安全默认配置搭建新的 Electron + React 项目：

deno run --allow-read --allow-write scripts/scaffold-electron-app.ts [options]

Options:
  --name <name>     App name (required)
  --path <path>     Target directory (default: ./)
  --with-react      Include React setup
  --with-trpc       Include electron-trpc
  --with-tests      Include Playwright tests

Examples:
  # Basic app with React
  deno run --allow-read --allow-write scripts/scaffold-electron-app.ts \
    --name "my-app" --with-react

  # Full setup with trpc and tests
  deno run --allow-read --allow-write scripts/scaffold-electron-app.ts \
    --name "my-app" --with-react --with-trpc --with-tests

generate-ipc-types.ts

根据 IPC 处理程序文件生成 TypeScript 类型定义：

deno run --allow-read --allow-write scripts/generate-ipc-types.ts [options]

Options:
  --handlers <path>  Path to IPC handler files
  --output <path>    Output path for type definitions
  --validate         Validate existing types match handlers

Examples:
  # Generate types from handlers
  deno run --allow-read --allow-write scripts/generate-ipc-types.ts \
    --handlers ./src/main/ipc --output ./src/preload/ipc-types.d.ts

  # Validate types in CI
  deno run --allow-read scripts/generate-ipc-types.ts \
    --handlers ./src/main/ipc --validate

其他资源

安全

• references/security/context-isolation.md - contextBridge 和隔离模式
• references/security/csp-and-permissions.md - 内容安全策略配置
• references/security/security-checklist.md - 完整的安全审计清单

IPC 通信

• references/ipc/typed-ipc.md - 类型化通道映射模式
• references/ipc/electron-trpc.md - 用于实现完整类型安全的 tRPC 集成
• references/ipc/error-serialization.md - 跨 IPC 边界传递 Result 类型

架构

• references/architecture/project-structure.md - 目录组织
• references/architecture/process-separation.md - 主进程、preload 和渲染进程的职责
• references/architecture/multi-window-state.md - 跨窗口共享状态

React 集成

• references/integration/react-patterns.md - useEffect 清理、Strict Mode
• references/integration/state-management.md - Zustand 和 electron-store 模式

打包与分发

• references/packaging/code-signing.md - 特定平台的签名工作流
• references/packaging/auto-updates.md - electron-updater 配置
• references/packaging/bundle-optimization.md - 缩减体积的技术
• references/packaging/ci-cd-patterns.md - GitHub Actions 矩阵构建

测试

• references/testing/playwright-e2e.md - Playwright 对 Electron 的支持
• references/testing/unit-testing.md - Jest/Vitest 多项目配置
• references/testing/test-structure.md - 测试组织模式

工具

• references/tooling/electron-vite.md - 构建工具配置
• references/tooling/electron-forge.md - 打包与分发
• references/tooling/tauri-comparison.md - 何时选择 Tauri

模板

• assets/templates/main-process.ts.md - 主进程起始模板
• assets/templates/preload-script.ts.md - 使用 contextBridge 的 preload 脚本
• assets/templates/ipc-handler.ts.md - IPC 处理程序模块模板
• assets/templates/react-root.tsx.md - React 根组件模板

配置示例

• assets/configs/electron-vite.config.ts.md - electron-vite 配置
• assets/configs/forge.config.js.md - Electron Forge 配置
• assets/configs/tsconfig.json.md - TypeScript 配置预设
• assets/configs/playwright.config.ts.md - Playwright Electron 测试配置

完整示例

• assets/examples/typed-ipc-example.md - 端到端类型化 IPC 演练
• assets/examples/multi-window-example.md - 多窗口状态管理