# Electron应用启动诊断流程 ## Electron 启动诊断流程样例 ### 场景 Electron 应用安装完成后能启动，但选择 workspace 后回到初始页，或者窗口变成空黑屏。 ### 诊断顺序 | 步骤 | 检查点 | 成功信号 | 失败信号 | | --- | --- | --- | --- | | 1 | `npm install` / postinstall | Electron zip 下载完成，依赖安装退出码为 0 | 长时间无退出但网络仍在下载，不能直接判死锁 | | 2 | 主进程状态 | 窗口创建成功，workspace 下生成 `.kanbots`，recents 被写入 | 无窗口、无 workspace 元数据、主进程日志异常 | | 3 | 渲染层 DOM | DevTools/CDP 可见 `#root` 有内容 | `#root` 为空或白/黑屏 | | 4 | preload/bridge | `window.<bridge>` 存在，关键 API 可调用 | bridge 缺失或调用 promise reject | | 5 | bootstrap 结果 | bootstrap promise 正常返回，并能解释当前 UI 状态 | bundle 抛错、IPC 断开、初始化卡住 | | 6 | recent workspace | 通过同一个 bridge 调用 openRecent/openWorkspace 后进入看板 | recent 已写入但不会自动打开，需要修业务启动逻辑 | ### 关键命令形态 ```bash ELECTRON_EXTRA_LAUNCH_ARGS="--remote-debugging-port=9222" npm run dev ``` 然后通过 CDP 执行： ```js Runtime.evaluate({ expression: "document.querySelector('#root')?.childElementCount" }) Runtime.evaluate({ expression: "Boolean(window.kanbots)" }) Runtime.evaluate({ expression: "window.kanbots.openWorkspace('/path/to/workspace')", awaitPromise: true }) ``` ### 预期结论模板 - 如果 postinstall 卡住但正在下载 darwin-arm64 zip：等待或配置 Electron mirror/cache，不改应用代码。 - 如果主进程写入 `.kanbots` 和 recents，但 `#root` 为空：优先查 renderer bundle、React mount、preload 注入。 - 如果 bridge 和 bootstrap 都正常，但不自动打开 recent：问题在业务启动策略；用 bridge 手动打开 recent 作为验证，再补自动恢复逻辑。