LobeHub Electron 的持久化 Hydration 不应由 React 挂载启动
内容提要
文章讨论LobeHub Electron应用冷启动时，业务内容短暂出现后回退至loading的问题。根因是hydration时机与React挂载不同步，导致缓存未恢复时UI先显示。解决方案是引入bootstrap层，并行启动初始化和渲染，用appReady gate控制可见性，并显式管理全局注册。优化后稳定首屏时间缩短44%，回退问题消除，并强调性能测试需物理隔离环境。
延伸解读
为何会出现“先显示后回退”
文章指出，问题根源在于持久化缓存的恢复（hydration）由 React Provider 或 useEffect 触发，而 React 调度决定触发时机，存储 I/O 决定完成时间。当子树在缓存恢复前订阅数据时，会先渲染空值并进入 Suspense，随后被 hydration 结果拉回业务 UI，造成视觉上的回退。这提醒开发者，UI 挂载不等于数据就绪，异步初始化必须显式管理。
并行启动与可见性门控
优化方案是引入 bootstrap 层，在 createRoot 之前同步启动初始化，但避免阻塞 React 模块求值。通过原子 appReady gate 控制业务 UI 可见性，使 CPU 与 I/O 并行，在可见性处汇合。flushSync 确保 ready 状态在 hydration 完成的同一微任务内提交，避免额外空白帧。这体现了“尚不可见”与“尚未解析”的区分，是提升启动性能的关键。
显式注册与副作用所有权
显式 bootstrap 暴露了循环依赖问题，根因是子包在顶层调用 registry，导入即修改全局 map。文章强调，注册应成为显式 API，由应用入口决定调用时刻，而非依赖 bundler 求值顺序。这提醒开发者，模块顶层的数组写入、map set、订阅等副作用都应明确所有权，否则边界不稳定。
性能测试的严谨性
文章强调性能测试需物理隔离环境，避免 dev server、HMR、source map 等污染测量。旧版本需放入独立 worktree 并重新安装依赖，防止 symlink 导致混合版本。同时，首屏指标必须覆盖“出现后回退”，定义稳定窗口（如连续 1500ms 不回退），否则可能提前报绿。这为性能验收提供了可复用的方法论。
Q&A
LobeHub Electron 冷启动时为什么业务内容会短暂出现后又退回 loading？
原因是持久化缓存的 hydration 由 React Provider 发起，UI 的挂载时刻被误用为数据准备的起点。React 调度决定触发时间，存储 I/O 决定完成时间，导致子树在缓存恢复之前订阅 key，先看到空值进入 Suspense，再被 hydration 结果拉回业务 UI。
LobeHub 是如何解决冷启动时 hydration 与 React 挂载不同步的问题的？
解决方案是引入 bootstrap 层，在 createRoot 之前同步启动初始化，但不阻塞 React 模块求值与路由构建。同时使用原子 appReady gate 控制业务 UI 的可见性，并显式管理全局注册。这样 CPU 线与 I/O 线可以并行，只有业务子树的显示需要等待 appReady。
为什么在 bootstrap 中要使用 flushSync 来设置 appReady？
flushSync 确保 ready 状态在 hydration 完成的同一微任务内提交，避免额外一帧空白，从而保证 UI 切换的流畅性。
LobeHub 在改造后遇到了哪些循环依赖问题？是如何解决的？
改造后，由于模块求值顺序变化，原来被偶然顺序掩盖的循环依赖开始报错，例如 'Cannot access AgentManagerRuntime before initialization'。根因是子包在顶层调用 registry，导入模块时同时修改全局 map。解决方法是注册成为显式 API，由应用入口决定调用时刻，例如通过 registerBuiltinToolSurfaces() 统一注册。
LobeHub 如何定义和测量稳定业务首屏？
稳定业务首屏的定义需要同时包含业务元素与连续稳定窗口：#root 可见；导航面板与首页主输入区出现；业务文本达到阈值；#loading-screen 不存在；以上条件连续 1500ms 不回退。
LobeHub 改造后性能提升的具体数据是多少？
稳定业务首屏中位数从 2615.8ms 降至 1465.8ms，缩短 44%；进程启动到稳定首屏中位数从 4848ms 降至 3796ms，缩短 22%；业务内容出现后回退从 2/3 降至 0/3。
为什么性能测试需要物理隔离环境？
因为 Dev server、HMR、source map 与未 tree-shake 的依赖会污染启动测量，所以对照使用生产 Electron 包。旧版本还必须放入独立 worktree 并重新安装依赖，否则 workspace symlink 可能让旧应用加载当前分支的新共享包，得到一个不存在于历史中的混合版本。
