推荐目录:
规则:
renderer 不能 import main 或 Node 内置模块。preload 只做桥接、参数校验、错误转换,不写业务。main 不 import renderer 的 UI 代码。shared 只放类型、常量、纯函数,不能有副作用。no-restricted-imports 强制边界。三个进程的运行时环境不同,建议分别构建:
| 目标 | 模块格式 | 目标环境 | 构建工具 |
|---|---|---|---|
| main | CJS/ESM | Node(Electron 内置) | tsc / esbuild / Vite |
| preload | CJS | 沙箱 preload | esbuild / Vite |
| renderer | ESM | Chromium | Vite / Webpack |
CI 中至少执行:
| 层级 | 工具 | 覆盖内容 |
|---|---|---|
| 单元测试 | Vitest | shared 纯函数、数据转换、校验逻辑 |
| 主进程集成 | Vitest + mock electron | IPC handler、服务层 |
| E2E | Playwright _electron | 启动、窗口、关键用户路径 |
| 冒烟测试 | 打包产物启动 | 安装包能否启动、版本号、基础页面 |
E2E 要跑在打包后的产物上,而不是开发服务器,才能覆盖 asar、路径、原生模块等真实差异。
关键原则:
node_modules 与构建产物,但避免缓存签名材料。| 指标 | 采集方式 | 门禁示例 |
|---|---|---|
| 安装包体积 | 构建产物 stat | 超过基线 5% 失败 |
app.asar 体积 | du/asar list | 超过基线 3% 失败 |
| 冷启动到首屏 | 自动化脚本埋点 | P95 超过 1.2s 失败 |
| 内存峰值 | 启动后固定操作序列采样 | 超过基线 10% 失败 |
| 首屏 JS 体积 | bundle 分析 | 超过预算失败 |
开发阶段可以在主进程与渲染进程打点:
生产环境应使用 app.getAppMetrics()、performance API 与自定义上报组合,并把结果按版本、平台、设备分桶。具体方案见启动性能优化。
如果使用自建上报,可以关闭自动上传,手动收集:
崩溃堆栈只有配合符号表才能读:
| 平台 | 符号 | 来源 |
|---|---|---|
| macOS | dSYM | 原生模块与自建 Electron 构建 |
| Windows | PDB | 原生模块与自建 Electron 构建 |
| Electron 自身 | 官方 symbols | Electron 发布页 的 symbols 包 |
流程:
注意:uncaughtException 之后进程状态可能已损坏,不要继续执行关键逻辑,应尽快上报并退出。
主进程的异步问题通常来自三类:
例外:启动阶段读取极小配置文件可以接受,但要测量耗时。
典型死锁:
避免方式:
sendSync。规范:
error / warn / info / debug。