用 Electron + React…

在生成 Electron 主进程/预加载/渲染进程代码、配置 electron-vite/Forge、设计 IPC、打包签名与测试时，提供安全优先的工程化做法。

适用场景

解决思路

1. 保持 Electron 20+ 的三大安全默认值：contextIsolation 开启、sandbox 开启、nodeIntegration 关闭；禁用任一项都会让 XSS 升级为远程代码执行。
2. 所有主进程与渲染进程通信都通过 contextBridge.exposeInMainWorld 暴露受控 API，例如 loadPreferences、saveFile、onUpdateCounter，而不是暴露原始 ipcRenderer。
3. 对加载本地文件的应用，通过 HTTP 响应头设置 Content Security Policy，将脚本来源限制为 'self'。
4. 请求-响应式通信优先使用 invoke/handle 模式而非 send/on，以获得正确的 async/await 语义和错误传播。
5. 用映射类型定义类型化 IPC 通道，例如 type IpcChannelMap = { 'load-prefs': { args: []; return: UserPreferences }; 'save-file': { args: [content: string]; return: { success: boolean } }; }。
6. 复杂应用可用 electron-trpc，基于 tRPC router 模式配合 Zod 校验获得完整类型安全，例如 t.procedure.input(z.object({ name: z.string() })).query(...)。
7. 跨 IPC 边界时用 { success, data, error } 结果类型包装响应，因为 Electron 只序列化 Error 的 message 属性，直接抛错会丢失上下文。
8. 采用推荐技术栈：开发用 electron-vite（统一管理 main/preload/renderer，亚秒级启动与即时 HMR），打包用 Electron Forge（使用官方包做签名与公证）。
9. 按 src/main（Node 环境）、src/preload（contextBridge 桥接与 index.d.ts 类型声明）、src/renderer（纯 Web React，无 Node 访问）组织目录结构。
10. 在 React 18 中正常使用并发特性；利用 Strict Mode 的双重调用效应检测 IPC 监听器泄漏，所有注册 IPC 监听的 useEffect 必须返回清理函数。
11. 多窗口应用以主进程作为共享状态的唯一来源，用 electron-store 持久化并结合 IPC 广播，使任一窗口的修改同步到其他窗口。
12. 创建 BrowserWindow 时始终设置 webPreferences: { preload: path.join(__dirname, '../preload/index.js'), contextIsolation: true, sandbox: true, nodeIntegration: false }，并确保 preload 路径指向构建产物。
13. 将相关 IPC handler 分组为模块，例如 registerFileHandlers 中用 ipcMain.handle('save-file', ...) 包裹 try/catch 并返回结果类型。
14. 对所有从渲染进程收到的 IPC 参数进行校验（Zod 或手动检查），防止注入攻击。
15. 本地服务器绑定 127.0.0.1，绝不绑定 0.0.0.0。
16. 为所有平台做代码签名与公证，避免操作系统安全警告和 Gatekeeper 拦截。
17. 测试使用 Playwright E2E，不要使用已废弃且最高只支持 Electron 13 的 Spectron。
18. 更新使用 electron-updater，而不是手动检查更新。
19. 简单应用状态管理用 Zustand + electron-store，不要为简单应用引入 Redux。
20. 构建工具用 electron-vite，避免基于 webpack 的工具链；打包用 Electron Forge，避免手动打包。
21. 用 scripts/analyze-security.ts 分析安全配置：deno run --allow-read scripts/analyze-security.ts <path>，支持 --strict、--json、-h/--help。
22. 用 scripts/scaffold-electron-app.ts 脚手架新项目：deno run --allow-read --allow-write scripts/scaffold-electron-app.ts --name <name> [--path <path>] [--with-react] [--with-trpc] [--with-tests]。
23. 用 scripts/generate-ipc-types.ts 从 IPC handler 生成类型：deno run --allow-read --allow-write scripts/generate-ipc-types.ts --handlers <path> --output <path>，或用 --validate 在 CI 中校验类型与 handler 一致。

适用边界 · 注意事项

• 构建 Tauri 应用（范式不同，应使用 Tauri 专属指南）。
• 构建无桌面需求的纯 Web 应用。
• 目标 Electron 版本低于 20（安全默认值不同）。
• 使用非 React 的渲染框架（应使用对应框架的技能）。