moai-framework-electron

Electron 33+ 桌面开发

快速参考

Electron 33+ 桌面应用开发专家可使用 Web 技术构建跨平台桌面应用。

自动触发条件：通过 electron.vite.config.ts 或 electron-builder.yml 文件检测到 Electron 项目、桌面应用开发请求、IPC 通信模式实现

核心功能

Electron 33 平台：

• Chromium 130 渲染引擎，支持现代 Web 功能
• Node.js 20.18 运行时，可访问原生系统功能
• 主进程原生支持 ESM
• 支持 WebGPU API，可实现 GPU 加速图形

进程架构：

• 每个应用运行一个主进程实例，拥有完整的 Node.js 访问权限
• 渲染进程在沙盒环境中显示 Web 内容
• 预加载脚本通过受控的 API 暴露连接主进程与渲染进程
• 工具进程处理后台任务，避免阻塞 UI

IPC 通信：

• 类型安全的 invoke/handle 模式，用于请求-响应通信
• contextBridge API 可让渲染进程安全地访问主进程功能
• 基于事件的消息传递，用于主进程向渲染进程推送通知

自动更新支持：

• 集成 electron-updater，并通过 GitHub 和 S3 发布
• 差分更新，缩小下载体积
• 更新通知和安装管理

打包选项：

• Electron Forge，提供集成构建工具和插件生态
• electron-builder，支持灵活的多平台分发

安全功能：

• 使用 contextIsolation 防止原型污染
• 强制启用 Sandbox，隔离渲染进程
• 配置内容安全策略
• IPC 处理程序的输入验证模式

项目初始化

创建新的 Electron 应用需要运行 create-electron-app 命令并使用 vite-typescript 模板。将 electron-builder 安装为开发依赖项以进行打包。将 electron-updater 添加为运行时依赖项以实现自动更新功能。

详细命令和配置请参阅 reference.md 的 Quick Commands 部分。

---

实现指南

项目结构

推荐目录布局：

源码目录应包含四个主要子目录：

主目录：包含主进程入口点、按领域组织的 IPC 处理程序定义、业务逻辑服务和窗口管理模块

Preload 目录：包含预加载脚本入口点和暴露的 API 定义，用于连接主进程与渲染进程

Renderer 目录：包含使用 React、Vue 或 Svelte 构建的 Web 应用，包括 HTML 入口点和 Vite 配置

Shared 目录：包含主进程与渲染进程共享的 TypeScript 类型和常量

项目根目录应包含用于构建配置的 electron.vite.config.ts、用于打包选项的 electron-builder.yml，以及用于存放应用图标和资源的 resources 目录。

主进程设置

应用生命周期管理：

主进程初始化遵循特定顺序。首先，使用 app.enableSandbox() 全局启用沙盒，确保所有渲染进程都在隔离环境中运行。然后请求单实例锁，以防止多个应用实例同时运行。

应在 app ready 事件触发后创建窗口。使用注重安全性的 webPreferences 配置 BrowserWindow，包括启用 contextIsolation、禁用 nodeIntegration、启用 sandbox 和启用 webSecurity。设置预加载脚本路径，以便向渲染进程暴露安全的 API。

处理特定于平台的行为：在 macOS 上，如果没有窗口，则在点击程序坞图标时重新创建窗口。在其他平台上，所有窗口关闭后退出应用。

实现示例请参阅 examples.md 的 Main Process Entry Point 部分。

类型安全的 IPC 通信

IPC 类型定义模式：

定义一个将通道名称映射到其负载类型的接口。按领域对通道分组，例如文件操作、窗口操作和存储操作。这样可以同时对主进程处理程序和渲染进程调用进行类型检查。

主进程处理程序注册：

在专用模块中注册 IPC 处理程序，并从共享类型中导入类型。每个处理程序在处理输入前都应使用 Zod 等模式验证库进行验证。对于请求-响应模式，请使用 ipcMain.handle 并返回结构化结果。

预加载脚本实现：

创建一个 API 对象，为每个通道封装 ipcRenderer.invoke 调用。使用 contextBridge.exposeInMainWorld 将此 API 作为 window.electronAPI 提供给渲染进程。为事件监听器添加清理函数，以防止内存泄漏。

完整的 IPC 实现模式请参阅 examples.md 中的 Type-Safe IPC Implementation 部分。

安全最佳实践

必需的安全设置：

每个 BrowserWindow 都必须配置 webPreferences 中的四项关键设置。必须始终启用 contextIsolation，以防止渲染进程代码访问 Electron 内部功能。必须始终在渲染进程中禁用 nodeIntegration。必须始终启用 sandbox，以实现进程级隔离。绝不能禁用 webSecurity，以维持同源策略的执行。

内容安全策略：

使用 webRequest.onHeadersReceived 配置会话级 CSP 标头。将 default-src 限制为 self，将 script-src 限制为不含 unsafe-inline 的 self，并将 connect-src 限制为允许的 API 域名。这样可以防止 XSS 攻击和未经授权的资源加载。

输入验证：

每个 IPC 处理程序都必须在处理输入前进行验证。拒绝包含父目录引用的路径，以防止路径遍历攻击。根据保留字符验证文件名。实现文件访问时，使用允许目录列表。

安全实现详情请参阅 reference.md 中的 Security Best Practices 部分。

自动更新实现

更新服务架构：

创建一个管理 electron-updater 生命周期的 UpdateService 类。初始化时传入主窗口引用，以便向 UI 发送通知。将 autoDownload 配置为 false，让用户能够控制带宽使用。

事件处理：

处理 update-available 事件，通知渲染进程并提示用户确认下载。跟踪 download-progress 事件以显示进度指示器。处理 update-downloaded 事件并提示用户重启。

用户通知模式：

使用系统对话框，在有可用更新和下载完成时提示用户。向渲染进程发送事件，以在应用内显示通知。支持立即安装和延后安装。

完整的更新服务实现请参阅 examples.md 中的 Auto-Update Integration 部分。

应用打包

Electron Builder 配置：

使用反向域名格式配置 appId，以便进行平台注册。指定 productName，以在系统 UI 中显示。为 macOS、Windows 和 Linux 设置特定于平台的目标。

macOS 配置：

设置 category，以便进行 App Store 分类。启用 hardenedRuntime 并配置用于公证的权限。配置同时面向 x64 和 arm64 架构的通用构建。

Windows 配置：

指定可执行文件和安装程序的图标路径。配置 NSIS 安装程序选项，包括安装目录选择。使用适当的哈希算法设置代码签名。

Linux 配置：

配置 category，以便集成桌面环境。设置多个目标，包括用于通用分发的 AppImage，以及用于通过包管理器安装的 deb/rpm。

完整的配置示例请参阅 reference.md 中的 Configuration 部分。

---

高级模式

有关高级主题的完整文档，请参阅 reference.md 和 examples.md：

窗口状态持久化：

• 在不同会话间保存和恢复窗口位置与大小
• 处理多个显示器及显示器变更
• 管理最大化和全屏状态

多窗口管理：

• 创建具有适当父子关系的辅助窗口
• 在多个窗口之间共享状态
• 协调窗口生命周期事件

系统托盘和原生菜单：

• 创建和更新带上下文菜单的系统托盘图标
• 构建带键盘快捷键的应用程序菜单
• 适用于 macOS 和 Windows 的平台特定菜单模式

实用进程：

• 为 CPU 密集型后台任务启动实用进程
• 通过 MessageChannel 与实用进程通信
• 管理实用进程的生命周期和错误处理

原生模块集成：

• 为 Electron 的 Node.js 版本重新构建原生模块
• 使用 better-sqlite3 进行本地数据库存储
• 集成 keytar 以安全存储凭据

协议处理程序和深层链接：

• 注册用于启动应用的自定义 URL 协议
• 在不同平台上处理深层链接
• 通过自定义协议处理 OAuth 回调

性能优化：

• 延迟加载窗口和大型模块
• 通过延迟初始化优化启动时间
• 管理长时间运行的应用程序的内存

---

配合使用效果良好

• .claude/rules/moai/languages/typescript.md - 类型安全的 Electron 开发 TypeScript 模式（通过 paths frontmatter 自动加载）
• moai-domain-frontend - React、Vue 或 Svelte 渲染进程开发
• .claude/rules/moai/languages/javascript.md - 主进程的 Node.js 模式（通过 paths frontmatter 自动加载）
• moai-domain-backend - 后端 API 集成
• moai-workflow-testing - 桌面应用测试策略

---

故障排除

常见问题和解决方案：

启动时白屏：

确认预加载脚本路径相对于构建输出目录正确配置。检查 loadFile 或 loadURL 路径是否指向现有文件。启用 devTools 以检查控制台错误。检查可能阻止脚本执行的 CSP 设置。

IPC 无法正常工作：

确认主进程处理程序和渲染进程调用中的通道名称完全一致。确保在窗口加载内容之前注册处理程序。验证 contextBridge 的用法是否遵循 exposeInMainWorld 的正确模式。

原生模块失败：

运行 electron-rebuild，在 npm install 后重新编译原生模块。确保与 Electron 内嵌的 Node.js 版本一致。添加 postinstall 脚本以自动重新构建。

自动更新无法正常工作：

确认应用程序已进行代码签名，因为更新需要签名。检查 electron-builder.yml 中的发布配置。启用 electron-updater 日志以诊断连接问题。检查可能阻止更新检查的防火墙设置。

调试命令：

使用 npx electron-rebuild 重新构建原生模块。使用 npx electron --version 检查 Electron 版本。使用 DEBUG=electron-updater 环境变量启用详细的更新日志记录。

---

资源

如需完整的代码示例和配置模板，请参阅：

• reference.md - 详细的 API 文档、版本矩阵、Context7 库映射
• examples.md - 涵盖所有模式、可用于生产环境的代码示例

如需最新文档，请使用 Context7 查询：

• /electron/electron，获取 Electron 核心 API
• /electron/forge，获取 Electron Forge 工具
• /electron-userland/electron-builder，获取打包配置

---

版本：2.0.0 最后更新：2026-01-10 变更：已重组以符合 CLAUDE.md 文档标准——删除所有代码示例，改为叙述性文本格式

常见的自我安慰

自我安慰	事实
“我可以在渲染进程中直接使用 Node.js API”	渲染进程运行的是不可信内容。直接访问 Node.js 会带来远程代码执行风险。请通过预加载桥接使用 IPC。
“我信任自己的代码，所以不需要 contextIsolation”	上下文隔离可以防止网页内容造成的原型污染影响 Node.js。这与是否信任自己的代码无关，而是为了隔离上下文。
“发布后再配置自动更新也来得及”	如果不提供自动更新，用户就会一直使用存在漏洞的版本。请在首次发布前完成配置。
“我之后再打包应用，现在用开发构建版本测试就够了”	开发构建版本的文件路径、权限和代码签名都不同。只有打包后的生产构建版本才能暴露实际分发问题。
“IPC 太慢了，我会通过全局变量共享状态”	IPC 的开销只有微秒级。全局变量会绕过出于安全考虑而设立的进程隔离。

危险信号

• 在 BrowserWindow 选项中将 nodeIntegration 设为 true
• 将 contextIsolation 设为 false，且没有记录安全方面的理由
• 渲染进程直接从 electron 或 node 模块导入内容（绕过预加载）
• 未配置自动更新机制
• IPC 处理程序未验证或清理来自渲染进程的参数

验证

• 所有 BrowserWindow 中的 nodeIntegration 均为 false，且 contextIsolation 均为 true
• 所有从渲染进程到主进程的通信都通过 contextBridge 和 IPC
• IPC 处理程序在处理输入参数前会进行验证
• 已配置并测试自动更新（展示更新配置）
• 使用 Electron Forge 成功打包应用（展示构建输出）
• 渲染进程代码中没有直接调用 require('electron')

遥测窗口

状态：不明确（60 天窗口） R4 审计结论：保留（监控） 规范：SPEC-V3R2-WF-001 §6.2 (REQ-WF001-013) 窗口开始日期：2026-04-25（Wave 1.5 提交日期） 窗口结束日期：2026-06-24（60 天） 重新审计触发条件：此技能的 SessionStart hook 激活次数 决策标准：

• 如果窗口期内激活次数 >= 5 → 永久保留
• 如果窗口期内激活次数 = 0 → 在 v3.1 中安排退役
• 如果 0 < 窗口期内激活次数 < 5 → 保留并添加“低使用率”标签