拓冰网站定制 
Tolaria 前端就绪看门狗Tauri 桌面应用如何识别“HTML 已渲染”与“应用真正可交互”【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria本篇基于 Tolaria 的架构决策记录 0104-tauri-frontend-readiness-watchdog讲解一个 Tauri 桌面应用中容易被忽视的启动失败模式——WebView 已经画出静态 HTML 外壳、但 React 应用始终没有挂载成功。读完本文你将掌握一套“HTML 引导脚本 React 就绪信号 一次性 WebView 重载”的跨层启动契约理解其 10 秒超时、sessionStorage防循环标记和 Tauri-only 门控的具体实现与测试验证方式。问题背景窗口“看起来启动了”但应用从未可交互Tolaria 已经把重文件系统和子进程工作移出了 Tauri 建窗路径但这只能防止“建窗慢”一类问题无法防住另一种启动失败桌面 WebView 渲染了静态 HTML 外壳而 React 应用永远没有变为可交互状态。在 macOS 上这种故障的表现是一个“看起来已启动、却从未完成真实应用挂载”的无响应窗口。ADR 明确把失败边界划在跨层之间四个关键点分别是index.html可以先于 React 提交而完成绘制Tolaria 有意如此见下文的启动外壳React 根节点的报错可能发生在应用报告“就绪”之前一次性的自动重载是合理的恢复手段但自动重载循环不可接受浏览器/模拟mock环境不应继承桌面专属的恢复行为。因此需要一份启动契约来区分“HTML 画出来了”和“前端真正可交互”并在契约不成立时提供一条有界的恢复路径。决策Tauri-only 就绪看门狗 一次性重载ADR 的最终决策是Tolaria 使用一个 Tauri 专属的前端就绪看门狗frontend-readiness watchdog如果 React 始终没有报告启动就绪则最多重载 WebView 一次。具体机制由六个要点构成全部对应仓库内的真实实现index.html在 React 加载之前安装一个 Tauri-only 的启动计时器见 index.html 中if (isTauri)分支React 在应用外壳提交后从一个已挂载的 effect 里派发就绪信号FrontendReadyMarker若超时前就绪信号未到达WebView 重载一次同一条一次性重载路径也开放给“就绪标记之前”的 React 根错误处理src/main.tsx 的captureReactRootErrorsessionStorage记录本次会话是否已经尝试过启动重载避免永远循环浏览器/mock 环境继续使用普通的浏览器 clipboard/storage 行为不启用这条桌面启动恢复路径。启动契约的三方构成ADR 的 Consequences 一节明确index.html、src/main.tsx与 src/utils/frontendReady.ts 共同构成一份共享启动契约未来的引导层重构必须保持它。下面按数据流顺序拆解。第一方index.html 中的看门狗脚本入口文件 index.html 内联了一段引导脚本它在script typemodule src/src/main.tsx执行之前运行因此能覆盖“React 模块根本没能执行”的最坏情况script const readyEventName tolaria:frontend-ready; const reloadAttemptKey tolaria:startup-reload-attempted; const startupTimeoutMs 10000; const isTauri __TAURI__ in window || __TAURI_INTERNALS__ in window; const hasReloadAttempted () { try { return sessionStorage.getItem(reloadAttemptKey) 1; } catch { return true; // 存储不可用时保守处理视为已尝试不再重载 } }; const markReloadAttempted () { try { sessionStorage.setItem(reloadAttemptKey, 1); return true; } catch { return false; // 存储不可写时放弃重载防止无状态可循环 } }; const reloadIfFrontendStalls () { if (window.__tolariaFrontendReady true) return; if (hasReloadAttempted()) return; if (!markReloadAttempted()) return; window.location.reload(); }; if (isTauri) { window.addEventListener(readyEventName, clearReloadAttempt, { once: true }); window.setTimeout(reloadIfFrontendStalls, startupTimeoutMs); } /script以上为按仓库实现整理的示意精确代码请以 index.html 为准。关键参数与设计取舍startupTimeoutMs 10000看门狗超时为 10 秒。ADR 特别警告任何未来改动若让应用外壳的挂载延迟超过这个阈值必须重新评估该超时和就绪触发点。isTauri门控通过检测window.__TAURI__或__TAURI_INTERNALS__判断是否运行在 Tauri WebView 中。只有桌面环境才会注册定时器与重载路径这正是“浏览器/mock 环境不继承桌面恢复行为”这一约束的落地方式——普通浏览器里isTauri为 false脚本体不会执行任何恢复逻辑。存储降级策略hasReloadAttempted在sessionStorage读取抛错时返回true视为已尝试、不重载markReloadAttempted写入失败时返回false放弃重载。注释说明这是为了应对“强化 WebView/隐私模式下存储不可用”的场景宁可少恢复一次也绝不制造无状态可记录的循环。就绪事件即“撤销重载”监听tolaria:frontend-ready事件的回调是clearReloadAttempt{ once: true }它清掉sessionStorage中的尝试标记。这样一次成功恢复后会话内若再次发生启动失败仍保留一次重载额度而重载本身会清除会话也天然防止连续多次自动重载。值得注意的旁证index.html同时承载了启动视觉外壳——div idtolaria-boot-shell内的骨架屏见 index.html以及一段克隆脚本把该节点存到window.__tolariaStartupShellFallbackNode供 React 侧的 StartupShellFallback 在Suspense挂起期间复用同一份 DOM。这解释了为什么“HTML 先画”是刻意为之的性能设计也让“画出了骨架屏”与“应用就绪”必须被明确区分开——看门狗正是为此而生。第二方React 侧的就绪信号FrontendReadyMarker 是一个返回null的哨兵组件export function FrontendReadyMarker() { useEffect(() { markFrontendReady() markStartupPhase(react_shell) }, []) return null }它被渲染在 src/main.tsx 的createRoot渲染树里、Suspense内部、懒加载的RootApp之后createRoot(getRequiredRootElement(), { onCaughtError: captureRecoverableReactRootError, onUncaughtError: captureReactRootError, onRecoverableError: captureRecoverableReactRootError, }).render( StrictMode TooltipProvider LinuxTitlebar / Suspense fallback{StartupShellFallback /} RootApp / FrontendReadyMarker / /Suspense /TooltipProvider /StrictMode, )把 marker 放在Suspense内部、且作为RootApp的兄弟节点意味着只有当懒加载的App.tsx模块完成解析、应用外壳真正提交渲染后useEffect才会执行——“就绪”的定义因此严格等于“应用外壳已挂载”而不是“模块开始加载”。第三方frontendReady.ts 的共享契约模块src/utils/frontendReady.ts 是三方共享的两个常量和两个函数的载体它保证引导脚本与 React 侧使用完全一致的信道名export const FRONTEND_READY_EVENT_NAME tolaria:frontend-ready export const STARTUP_RELOAD_ATTEMPT_STORAGE_NAME tolaria:startup-reload-attempted核心 API 有两个均支持注入storage/win/reload选项以便单元测试export function markFrontendReady(options: FrontendReadyOptions {}): void { const win options.win ?? window const storage options.storage ?? getSessionStorage(win) win.__tolariaFrontendReady true // ① 置就绪标志看门狗脚本读的就是它 removeSessionItem(storage, STARTUP_RELOAD_ATTEMPT_STORAGE_NAME) // ② 清掉重载尝试标记 win.dispatchEvent(new Event(FRONTEND_READY_EVENT_NAME)) // ③ 派发就绪事件 } export function reloadFrontendOnceIfStartupFailed(options: StartupReloadOptions {}): boolean { const win startupWindow(options.win) const storage startupStorage(options.storage, win) if (!startupNeedsReload(win, storage)) return false if (!writeSessionItem(storage, STARTUP_RELOAD_ATTEMPT_STORAGE_NAME, 1)) return false const reload startupReload(options.reload, win) reload() return true }markFrontendReady做三件事与index.html看门狗脚本严丝合缝地对应置window.__tolariaFrontendReady true让已排定的setTimeout回调到时直接返回、清除会话标记为将来恢复一次重载额度、派发tolaria:frontend-ready事件触发引导脚本里的clearReloadAttempt。reloadFrontendOnceIfStartupFailed则是“同一一次性重载路径”的 React 侧入口。判定逻辑startupNeedsReload要求同时满足两个条件才允许重载function startupNeedsReload(win: Window, storage: Storage | null): boolean { if (win.__tolariaFrontendReady true) return false return readSessionItem(storage, STARTUP_RELOAD_ATTEMPT_STORAGE_NAME) ! 1 }即“尚未就绪”且“本会话尚未尝试过重载”。写入标记失败如存储不可用时同样放弃重载返回false——与引导脚本的降级策略一致。与 React 根错误处理的接线看门狗的定时器只覆盖“静默卡死”React 根本没跑起来而“模块能加载但渲染立即抛错”这类失败则由 src/main.tsx 中传给createRoot的onUncaughtError钩子兜住function captureReactRootError(error: unknown, errorInfo: { componentStack?: string }): void { if (isResizeObserverLoopError(error)) return if (isStartupDefaultExportImportError(error) reloadFrontendOnceIfStartupFailed()) return const componentStack errorInfo.componentStack ?? showFatalRenderError(error, { componentStack }) sentryReactErrorHandler(error, { componentStack }) reloadFrontendOnceIfStartupFailed() }这里有两层防护启动期 chunk 错误短路isStartupDefaultExportImportError精确匹配两条典型的懒加载模块损坏信息Cannot read properties of undefined (reading default)与 WebKit 的undefined is not an object (evaluating o.default)。若命中且reloadFrontendOnceIfStartupFailed()成功触发了重载函数直接return——不上报 Sentry、不弹致命错误浮层让重载去完成恢复。一般未捕获根错误先展示致命错误浮层、上报 Sentry最后才尝试一次性重载。由于startupNeedsReload要求“尚未就绪”启动完成后__tolariaFrontendReady true发生的运行时错误永远不会触发意外重载——这正是 ADR 里“post-startup runtime errors should not trigger surprise reloads”约束的实现保证。恢复若成功重新加载后的页面会再次走完挂载流程并由FrontendReadyMarker报告就绪若失败依旧ADR 的立场是一次性重试之后 Tolaria 仍然把坏状态显式暴露出来致命错误浮层 Sentry 上报而不是用反复重载掩盖更深层的 bug。为什么选择这个方案ADR 中的备选比较ADR 记录了四个候选方案的权衡这也是理解这套设计边界的最好材料方案结论理由Tauri-only 就绪看门狗 一次性重载选中采用直接针对“无响应启动”故障模式恢复逻辑完全留在前端避免永久性重载循环。代价是启动现在依赖 HTML 引导与 React 之间一份小小的跨层契约什么都不做依赖用户手动重启否决实现最简单但让用户困在“看起来坏了”的应用状态里没有任何自动恢复任何 React 根错误都重载无就绪门控否决过于激进且噪音大启动完成后的运行时错误不应触发意外重载把恢复完全下放到原生 Rust 窗口/引导逻辑否决可行但失败信号本身存在于前端生命周期里原生代码最终还是需要一个就绪握手从源码结构看这个决策也解释了为什么isTauri判定同时出现在index.html与 src/main.tsxisTauriRuntime()两处桌面专属行为被系统性地门控在“真 Tauri 运行时”内浏览器与 mock 路径保持干净。结果与维护契约按 ADR 的 Consequences这套机制带来五个长期约束值得后续改动者逐条对照Tolaria 从此把“前端启动成功”与“仅仅渲染了 HTML 外壳”区分开来桌面启动恢复被限定为每会话单次重试降低把用户困进重载循环的概率index.html、src/main.tsx与src/utils/frontendReady.ts构成共享启动契约任何未来引导层重构必须保持它任何让应用外壳挂载延迟超过看门狗超时的改动都必须重新评估超时值与就绪触发点若启动失败在重试一次后仍然存在Tolaria 仍然表面化这个坏状态而不是用反复重载掩盖更深层的 bug。测试验证契约的每一条边都被覆盖这套跨层契约的可信度来自两组单元/集成测试src/utils/frontendReady.test.ts直接验证契约原语markFrontendReady置标志、清掉待处理的重载标记、且只派发一次就绪事件reloadFrontendOnceIfStartupFailed首次调用返回true并触发注入的reload第二次返回false且不再重载markFrontendReady之后再调用重载函数则完全不触发reload。src/main.test.ts验证入口接线在就绪前抛出Cannot read properties of undefined (reading default)这类启动 chunk 错误时sessionStorage写入tolaria:startup-reload-attempted 1Sentry 不被调用、致命浮层不出现——即重载成功接管了错误恢复而不是让用户看到报错。配合引导脚本自身的降级分支存储不可读 → 视为已尝试存储不可写 → 放弃重载整个恢复路径在“一切正常、部分失效、彻底失败”三种情形下都有确定行为且所有自动恢复都被sessionStorage标记限定在每会话一次以内。小结Tolaria 的 ADR 0104 给出的是一个通用的桌面端 React 应用启动可靠性范式用index.html内联脚本提供“模块都加载失败”时的最后防线用Suspense内的就绪 marker 精确定义“应用外壳已挂载”用一个共享 TS 模块统一事件名、存储键与重载判定再用手写超时 一次性location.reload()构成有界的自动恢复闭环同时用isTauri门控把桌面专属行为隔离在浏览器环境之外。对任何使用 Tauri或 Electron构建 React 桌面应用的项目这套“HTML 画了 ≠ 应用就绪”的启动契约与防循环重载设计都可直接参照复用。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Tolaria 前端就绪看门狗：Tauri 桌面应用如何识别“HTML 已渲染”与“应用真正可交互”
Tolaria 前端就绪看门狗Tauri 桌面应用如何识别“HTML 已渲染”与“应用真正可交互”【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria本篇基于 Tolaria 的架构决策记录 0104-tauri-frontend-readiness-watchdog讲解一个 Tauri 桌面应用中容易被忽视的启动失败模式——WebView 已经画出静态 HTML 外壳、但 React 应用始终没有挂载成功。读完本文你将掌握一套“HTML 引导脚本 React 就绪信号 一次性 WebView 重载”的跨层启动契约理解其 10 秒超时、sessionStorage防循环标记和 Tauri-only 门控的具体实现与测试验证方式。问题背景窗口“看起来启动了”但应用从未可交互Tolaria 已经把重文件系统和子进程工作移出了 Tauri 建窗路径但这只能防止“建窗慢”一类问题无法防住另一种启动失败桌面 WebView 渲染了静态 HTML 外壳而 React 应用永远没有变为可交互状态。在 macOS 上这种故障的表现是一个“看起来已启动、却从未完成真实应用挂载”的无响应窗口。ADR 明确把失败边界划在跨层之间四个关键点分别是index.html可以先于 React 提交而完成绘制Tolaria 有意如此见下文的启动外壳React 根节点的报错可能发生在应用报告“就绪”之前一次性的自动重载是合理的恢复手段但自动重载循环不可接受浏览器/模拟mock环境不应继承桌面专属的恢复行为。因此需要一份启动契约来区分“HTML 画出来了”和“前端真正可交互”并在契约不成立时提供一条有界的恢复路径。决策Tauri-only 就绪看门狗 一次性重载ADR 的最终决策是Tolaria 使用一个 Tauri 专属的前端就绪看门狗frontend-readiness watchdog如果 React 始终没有报告启动就绪则最多重载 WebView 一次。具体机制由六个要点构成全部对应仓库内的真实实现index.html在 React 加载之前安装一个 Tauri-only 的启动计时器见 index.html 中if (isTauri)分支React 在应用外壳提交后从一个已挂载的 effect 里派发就绪信号FrontendReadyMarker若超时前就绪信号未到达WebView 重载一次同一条一次性重载路径也开放给“就绪标记之前”的 React 根错误处理src/main.tsx 的captureReactRootErrorsessionStorage记录本次会话是否已经尝试过启动重载避免永远循环浏览器/mock 环境继续使用普通的浏览器 clipboard/storage 行为不启用这条桌面启动恢复路径。启动契约的三方构成ADR 的 Consequences 一节明确index.html、src/main.tsx与 src/utils/frontendReady.ts 共同构成一份共享启动契约未来的引导层重构必须保持它。下面按数据流顺序拆解。第一方index.html 中的看门狗脚本入口文件 index.html 内联了一段引导脚本它在script typemodule src/src/main.tsx执行之前运行因此能覆盖“React 模块根本没能执行”的最坏情况script const readyEventName tolaria:frontend-ready; const reloadAttemptKey tolaria:startup-reload-attempted; const startupTimeoutMs 10000; const isTauri __TAURI__ in window || __TAURI_INTERNALS__ in window; const hasReloadAttempted () { try { return sessionStorage.getItem(reloadAttemptKey) 1; } catch { return true; // 存储不可用时保守处理视为已尝试不再重载 } }; const markReloadAttempted () { try { sessionStorage.setItem(reloadAttemptKey, 1); return true; } catch { return false; // 存储不可写时放弃重载防止无状态可循环 } }; const reloadIfFrontendStalls () { if (window.__tolariaFrontendReady true) return; if (hasReloadAttempted()) return; if (!markReloadAttempted()) return; window.location.reload(); }; if (isTauri) { window.addEventListener(readyEventName, clearReloadAttempt, { once: true }); window.setTimeout(reloadIfFrontendStalls, startupTimeoutMs); } /script以上为按仓库实现整理的示意精确代码请以 index.html 为准。关键参数与设计取舍startupTimeoutMs 10000看门狗超时为 10 秒。ADR 特别警告任何未来改动若让应用外壳的挂载延迟超过这个阈值必须重新评估该超时和就绪触发点。isTauri门控通过检测window.__TAURI__或__TAURI_INTERNALS__判断是否运行在 Tauri WebView 中。只有桌面环境才会注册定时器与重载路径这正是“浏览器/mock 环境不继承桌面恢复行为”这一约束的落地方式——普通浏览器里isTauri为 false脚本体不会执行任何恢复逻辑。存储降级策略hasReloadAttempted在sessionStorage读取抛错时返回true视为已尝试、不重载markReloadAttempted写入失败时返回false放弃重载。注释说明这是为了应对“强化 WebView/隐私模式下存储不可用”的场景宁可少恢复一次也绝不制造无状态可记录的循环。就绪事件即“撤销重载”监听tolaria:frontend-ready事件的回调是clearReloadAttempt{ once: true }它清掉sessionStorage中的尝试标记。这样一次成功恢复后会话内若再次发生启动失败仍保留一次重载额度而重载本身会清除会话也天然防止连续多次自动重载。值得注意的旁证index.html同时承载了启动视觉外壳——div idtolaria-boot-shell内的骨架屏见 index.html以及一段克隆脚本把该节点存到window.__tolariaStartupShellFallbackNode供 React 侧的 StartupShellFallback 在Suspense挂起期间复用同一份 DOM。这解释了为什么“HTML 先画”是刻意为之的性能设计也让“画出了骨架屏”与“应用就绪”必须被明确区分开——看门狗正是为此而生。第二方React 侧的就绪信号FrontendReadyMarker 是一个返回null的哨兵组件export function FrontendReadyMarker() { useEffect(() { markFrontendReady() markStartupPhase(react_shell) }, []) return null }它被渲染在 src/main.tsx 的createRoot渲染树里、Suspense内部、懒加载的RootApp之后createRoot(getRequiredRootElement(), { onCaughtError: captureRecoverableReactRootError, onUncaughtError: captureReactRootError, onRecoverableError: captureRecoverableReactRootError, }).render( StrictMode TooltipProvider LinuxTitlebar / Suspense fallback{StartupShellFallback /} RootApp / FrontendReadyMarker / /Suspense /TooltipProvider /StrictMode, )把 marker 放在Suspense内部、且作为RootApp的兄弟节点意味着只有当懒加载的App.tsx模块完成解析、应用外壳真正提交渲染后useEffect才会执行——“就绪”的定义因此严格等于“应用外壳已挂载”而不是“模块开始加载”。第三方frontendReady.ts 的共享契约模块src/utils/frontendReady.ts 是三方共享的两个常量和两个函数的载体它保证引导脚本与 React 侧使用完全一致的信道名export const FRONTEND_READY_EVENT_NAME tolaria:frontend-ready export const STARTUP_RELOAD_ATTEMPT_STORAGE_NAME tolaria:startup-reload-attempted核心 API 有两个均支持注入storage/win/reload选项以便单元测试export function markFrontendReady(options: FrontendReadyOptions {}): void { const win options.win ?? window const storage options.storage ?? getSessionStorage(win) win.__tolariaFrontendReady true // ① 置就绪标志看门狗脚本读的就是它 removeSessionItem(storage, STARTUP_RELOAD_ATTEMPT_STORAGE_NAME) // ② 清掉重载尝试标记 win.dispatchEvent(new Event(FRONTEND_READY_EVENT_NAME)) // ③ 派发就绪事件 } export function reloadFrontendOnceIfStartupFailed(options: StartupReloadOptions {}): boolean { const win startupWindow(options.win) const storage startupStorage(options.storage, win) if (!startupNeedsReload(win, storage)) return false if (!writeSessionItem(storage, STARTUP_RELOAD_ATTEMPT_STORAGE_NAME, 1)) return false const reload startupReload(options.reload, win) reload() return true }markFrontendReady做三件事与index.html看门狗脚本严丝合缝地对应置window.__tolariaFrontendReady true让已排定的setTimeout回调到时直接返回、清除会话标记为将来恢复一次重载额度、派发tolaria:frontend-ready事件触发引导脚本里的clearReloadAttempt。reloadFrontendOnceIfStartupFailed则是“同一一次性重载路径”的 React 侧入口。判定逻辑startupNeedsReload要求同时满足两个条件才允许重载function startupNeedsReload(win: Window, storage: Storage | null): boolean { if (win.__tolariaFrontendReady true) return false return readSessionItem(storage, STARTUP_RELOAD_ATTEMPT_STORAGE_NAME) ! 1 }即“尚未就绪”且“本会话尚未尝试过重载”。写入标记失败如存储不可用时同样放弃重载返回false——与引导脚本的降级策略一致。与 React 根错误处理的接线看门狗的定时器只覆盖“静默卡死”React 根本没跑起来而“模块能加载但渲染立即抛错”这类失败则由 src/main.tsx 中传给createRoot的onUncaughtError钩子兜住function captureReactRootError(error: unknown, errorInfo: { componentStack?: string }): void { if (isResizeObserverLoopError(error)) return if (isStartupDefaultExportImportError(error) reloadFrontendOnceIfStartupFailed()) return const componentStack errorInfo.componentStack ?? showFatalRenderError(error, { componentStack }) sentryReactErrorHandler(error, { componentStack }) reloadFrontendOnceIfStartupFailed() }这里有两层防护启动期 chunk 错误短路isStartupDefaultExportImportError精确匹配两条典型的懒加载模块损坏信息Cannot read properties of undefined (reading default)与 WebKit 的undefined is not an object (evaluating o.default)。若命中且reloadFrontendOnceIfStartupFailed()成功触发了重载函数直接return——不上报 Sentry、不弹致命错误浮层让重载去完成恢复。一般未捕获根错误先展示致命错误浮层、上报 Sentry最后才尝试一次性重载。由于startupNeedsReload要求“尚未就绪”启动完成后__tolariaFrontendReady true发生的运行时错误永远不会触发意外重载——这正是 ADR 里“post-startup runtime errors should not trigger surprise reloads”约束的实现保证。恢复若成功重新加载后的页面会再次走完挂载流程并由FrontendReadyMarker报告就绪若失败依旧ADR 的立场是一次性重试之后 Tolaria 仍然把坏状态显式暴露出来致命错误浮层 Sentry 上报而不是用反复重载掩盖更深层的 bug。为什么选择这个方案ADR 中的备选比较ADR 记录了四个候选方案的权衡这也是理解这套设计边界的最好材料方案结论理由Tauri-only 就绪看门狗 一次性重载选中采用直接针对“无响应启动”故障模式恢复逻辑完全留在前端避免永久性重载循环。代价是启动现在依赖 HTML 引导与 React 之间一份小小的跨层契约什么都不做依赖用户手动重启否决实现最简单但让用户困在“看起来坏了”的应用状态里没有任何自动恢复任何 React 根错误都重载无就绪门控否决过于激进且噪音大启动完成后的运行时错误不应触发意外重载把恢复完全下放到原生 Rust 窗口/引导逻辑否决可行但失败信号本身存在于前端生命周期里原生代码最终还是需要一个就绪握手从源码结构看这个决策也解释了为什么isTauri判定同时出现在index.html与 src/main.tsxisTauriRuntime()两处桌面专属行为被系统性地门控在“真 Tauri 运行时”内浏览器与 mock 路径保持干净。结果与维护契约按 ADR 的 Consequences这套机制带来五个长期约束值得后续改动者逐条对照Tolaria 从此把“前端启动成功”与“仅仅渲染了 HTML 外壳”区分开来桌面启动恢复被限定为每会话单次重试降低把用户困进重载循环的概率index.html、src/main.tsx与src/utils/frontendReady.ts构成共享启动契约任何未来引导层重构必须保持它任何让应用外壳挂载延迟超过看门狗超时的改动都必须重新评估超时值与就绪触发点若启动失败在重试一次后仍然存在Tolaria 仍然表面化这个坏状态而不是用反复重载掩盖更深层的 bug。测试验证契约的每一条边都被覆盖这套跨层契约的可信度来自两组单元/集成测试src/utils/frontendReady.test.ts直接验证契约原语markFrontendReady置标志、清掉待处理的重载标记、且只派发一次就绪事件reloadFrontendOnceIfStartupFailed首次调用返回true并触发注入的reload第二次返回false且不再重载markFrontendReady之后再调用重载函数则完全不触发reload。src/main.test.ts验证入口接线在就绪前抛出Cannot read properties of undefined (reading default)这类启动 chunk 错误时sessionStorage写入tolaria:startup-reload-attempted 1Sentry 不被调用、致命浮层不出现——即重载成功接管了错误恢复而不是让用户看到报错。配合引导脚本自身的降级分支存储不可读 → 视为已尝试存储不可写 → 放弃重载整个恢复路径在“一切正常、部分失效、彻底失败”三种情形下都有确定行为且所有自动恢复都被sessionStorage标记限定在每会话一次以内。小结Tolaria 的 ADR 0104 给出的是一个通用的桌面端 React 应用启动可靠性范式用index.html内联脚本提供“模块都加载失败”时的最后防线用Suspense内的就绪 marker 精确定义“应用外壳已挂载”用一个共享 TS 模块统一事件名、存储键与重载判定再用手写超时 一次性location.reload()构成有界的自动恢复闭环同时用isTauri门控把桌面专属行为隔离在浏览器环境之外。对任何使用 Tauri或 Electron构建 React 桌面应用的项目这套“HTML 画了 ≠ 应用就绪”的启动契约与防循环重载设计都可直接参照复用。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考