HarmonyOS应用实战-启示散页-45-资源缺失别等首页白屏：启动期做轻量资源预检

HarmonyOS应用实战-启示散页-45-资源缺失别等首页白屏启动期做轻量资源预检默认题库依赖 rawfile。路径写错、JSON 损坏或答案全为空时用户看到的往往不是明确错误而是首页没有可抽取内容。启动期预检不是把全包扫一遍而是先确认首屏必须资源能不能支撑应用进入可恢复状态。这篇文章解决四件事还原这个问题在答案之书这类离线应用里如何出现。明确页面、Service、Repository、AppStorage 或发布清单各自的责任。给出可迁移的 ArkTS/工程代码片段并说明反例为什么会留下隐患。用验证清单和排障表把方案收成可执行检查项。资源错误最怕被包装成空态首页白屏时团队常先查布局、路由和主题最后才发现是 seed 文件缺失。更稳的做法是在启动链路早期生成一份轻量 Probe 结果缺文件、格式错、内容不可用要分开记录页面据此显示恢复入口而不是把所有异常都变成“暂无题库”。已核对的现状是SeedLoader 读取 rawfile/seed/default_deck.json解析并过滤空答案错误会被记录且不会阻止 loadContent。本文的 StartupResourceProbe 是建议新增的启动阻断资源检查。预检只覆盖启动阻断资源先写 owner 表再写代码。否则代码能跑起来却很难说明失败时该由谁回滚、重启后该由谁恢复、其他页面该根据什么信号刷新。Owner负责什么不负责什么EntryAbility触发启动预检并决定是否继续播种读取所有图片、文章素材或发布文件StartupResourceProbe检查首屏必须 rawfile 和最小可用数据承担页面展示SeedLoader在 Probe 通过后执行播种和升级合并吞掉所有异常RecoveryPage展示可恢复结果和下一步操作直接修 rawfileProbeResult 要能解释资源失败原因模型要表达本链路需要的稳定事实不要把页面临时状态或底层存储细节暴露出去。这样后续迁移 Preferences schema、拆模块或增加发布检查时调用方不必跟着重写。typeProbeStatusready|missing|invalid|empty;interfaceStartupResourceProbeResult{resourcePath:string;status:ProbeStatus;answerCount:number;recoverable:boolean;message:string;}这段模型的重点有三点字段命名贴近业务输入输出能覆盖失败分支没有携带 ArkUI 组件状态。页面拿它展示Service 拿它做判断Repository 不需要知道页面长什么样。Probe 只读最小资源不接管播种Service 是规则 owner。凡是涉及校验、回滚、冲突、恢复、隐私或发布证据的逻辑都不要散落在组件回调里。classStartupResourceProbe{asynccheckDefaultDeck(resourceManager:resourceManager.ResourceManager):PromiseStartupResourceProbeResult{constpathseed/default_deck.json;try{constrawawaitresourceManager.getRawFileContent(path);constdeckJSON.parse(buffer.from(raw).toString());constanswerCountArray.isArray(deck.answers)?deck.answers.filter((item:string)item.trim().length0).length:0;if(answerCount0){return{resourcePath:path,status:empty,answerCount,recoverable:true,message:默认题库没有可用答案};}return{resourcePath:path,status:ready,answerCount,recoverable:false,message:默认题库可用};}catch(error){return{resourcePath:path,status:invalid,answerCount:0,recoverable:true,message:默认题库读取或解析失败};}}}这里的 Service 不追求复杂抽象只做一件事把输入转成可解释结果。页面可以做乐观交互但最终事实必须从 Service 返回。把最近一次预检结果留给恢复页Repository 负责稳定读写、默认值和 schema 兼容。它不弹 Toast不决定按钮状态也不拼页面文案。classStartupLedgerRepository{staticasyncsaveProbeResult(result:StartupResourceProbeResult):Promisevoid{awaitPreferencesStore.setJson(startup_ledger,last_resource_probe,{...result,checkedAt:Date.now()});}staticasyncloadProbeResult():PromiseStartupResourceProbeResult|null{returnPreferencesStore.getJsonStartupResourceProbeResult(startup_ledger,last_resource_probe);}}如果这一层缺失页面会被迫知道 store name、key、默认值和异常处理细节。写到后面所有页面都会变成半个仓储层。EntryAbility 决定继续播种还是进入恢复页页面只消费结果、展示状态、触发动作。跨页面刷新用轻量信号完整业务对象继续由 Service 重新读取。classEntryBootstrap{asyncrun(context:UIAbilityContext,windowStage:window.WindowStage):Promisevoid{constprobeawaitnewStartupResourceProbe().checkDefaultDeck(context.resourceManager);awaitStartupLedgerRepository.saveProbeResult(probe);if(probe.status!readyprobe.recoverable){awaitthis.loadRecoveryPage(windowStage,probe);return;}awaitSeedLoader.run(context);awaitwindowStage.loadContent(pages/Index);}}这类写法的好处是入口可以扩展页面可以重进数据可以迁移。只要 Service 和 Repository 边界稳定页面不需要关心底层怎么保存。反例短期省事长期失控反例是在 SeedLoader 的 catch 里只打一条日志然后继续 loadContent。这样构建能过、页面也能进但用户看到的是空首页开发者排查时也拿不到“缺文件、格式错、内容为空”的区别。更具体地说反例通常有三个共同点直接写持久化、没有失败结果、没有刷新 owner。它们在单次手测里很难暴露但在重启、返回、跨入口或发布复查时会变成真实问题。排查顺序\n1. 先找唯一写入 owner。\n2. 再看失败是否返回可展示结果。\n3. 再看刷新信号是否只通知相关页面。\n4. 最后才检查 UI 展示。验证路径不要只走正常操作把 default_deck.json 临时改成非法 JSON确认进入恢复页并显示 invalid。准备 answers 全为空的 seed确认状态是 empty而不是普通空题库。恢复正确 rawfile 后重新启动确认 Probe ready 后才进入首页。检查预检只读取首屏阻断资源没有扫描 CSDN 图片目录或非启动资源。验证时建议把“正常路径、异常输入、重启恢复、跨入口刷新、发布态检查”分开记录。构建通过只能证明语法和资源能打包不能证明这些运行链路都已经被真机验证。rg-nPreferencesStore|AppStorage.setOrCreate|Repository|ServiceD:\\ProgramData\\huawei\\lesson\\The_Book_of_Answers\nrg-nquestion|answerText|deckName|hilogD:\\ProgramData\\huawei\\lesson\\The_Book_of_Answers常见问题与处理现象先看哪里处理首页空白但日志无异常SeedLoader 是否吞掉错误保存 ProbeResult 并给恢复页读取启动明显变慢是否全量扫描资源目录只检查首屏必须 rawfileJSON 能解析但题库不可用是否校验 answers 数量把 empty 与 invalid 分开处理这些问题时不要先改 UI 文案。先确认写入 owner、读取 owner 和刷新信号是否一致再看页面是否正确消费结果。若只在页面补一个 Toast用户当次可能看到了提示但重启、返回、跨入口和发布复查仍然会暴露同一个根因。落地取舍这套方案不是为了把轻量应用写重而是为了把真正会跨页面、跨启动、跨发布阶段的事实收住。只影响当前展示节奏的变量可以留在页面会改变用户内容、持久结构、隐私口径或发布证据的逻辑必须进入 Service、Repository 或发布清单。判断点建议位置原因只影响当前按钮、弹层或动画页面State不需要跨入口复用会写本地数据或读持久事实Service Repository需要校验、回滚和恢复会影响其他页面刷新AppStorage 时间戳通知变化不共享完整对象会影响发布、截图、隐私或诊断发布清单或运行账本后续复查需要证据真正落地时可以先从一条最容易复现的路径开始找出唯一写入点补上结果模型再把页面里的直接读写替换成 Service 调用。这个顺序比一次性重构全部页面更稳也更容易在评审时说明每一行代码解决了哪个故障链。评审记录里最好保留对应的命令、截图或复现步骤避免方案只停留在口头约定。小结启动预检的价值是把资源问题变成可解释状态。它不应该替代 SeedLoader也不应该扫描整包只要能在首屏前识别阻断资源并给恢复页留下证据就足够解决“资源缺失却表现成白屏”的排障断点。更容易在评审时说明每一行代码解决了哪个故障链。评审记录里最好保留对应的命令、截图或复现步骤避免方案只停留在口头约定。小结启动预检的价值是把资源问题变成可解释状态。它不应该替代 SeedLoader也不应该扫描整包只要能在首屏前识别阻断资源并给恢复页留下证据就足够解决“资源缺失却表现成白屏”的排障断点。