企业官网建设流程全解析

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

默认题库依赖 rawfile。路径写错、JSON 损坏或答案全为空时，用户看到的往往不是明确错误，而是首页没有可抽取内容。启动期预检不是把全包扫一遍，而是先确认首屏必须资源能不能支撑应用进入可恢复状态。

这篇文章解决四件事：

1. 还原这个问题在答案之书这类离线应用里如何出现。
2. 明确页面、Service、Repository、AppStorage 或发布清单各自的责任。
3. 给出可迁移的 ArkTS/工程代码片段，并说明反例为什么会留下隐患。
4. 用验证清单和排障表把方案收成可执行检查项。

资源错误最怕被包装成空态

首页白屏时，团队常先查布局、路由和主题，最后才发现是 seed 文件缺失。更稳的做法是在启动链路早期生成一份轻量 Probe 结果：缺文件、格式错、内容不可用要分开记录，页面据此显示恢复入口，而不是把所有异常都变成“暂无题库”。

已核对的现状是：SeedLoader 读取 rawfile/seed/default_deck.json，解析并过滤空答案；错误会被记录且不会阻止 loadContent。本文的 StartupResourceProbe 是建议新增的启动阻断资源检查。

预检只覆盖启动阻断资源

先写 owner 表，再写代码。否则代码能跑起来，却很难说明失败时该由谁回滚、重启后该由谁恢复、其他页面该根据什么信号刷新。

ProbeResult 要能解释资源失败原因

模型要表达本链路需要的稳定事实，不要把页面临时状态或底层存储细节暴露出去。这样后续迁移 Preferences schema、拆模块或增加发布检查时，调用方不必跟着重写。

typeProbeStatus='ready'|'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):Promise<StartupResourceProbeResult>{constpath='seed/default_deck.json';try{constraw=awaitresourceManager.getRawFileContent(path);constdeck=JSON.parse(buffer.from(raw).toString());constanswerCount=Array.isArray(deck.answers)?deck.answers.filter((item:string)=>item.trim().length>0).length:0;if(answerCount===0){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):Promise<void>{awaitPreferencesStore.setJson('startup_ledger','last_resource_probe',{...result,checkedAt:Date.now()});}staticasyncloadProbeResult():Promise<StartupResourceProbeResult|null>{returnPreferencesStore.getJson<StartupResourceProbeResult>('startup_ledger','last_resource_probe');}}

如果这一层缺失，页面会被迫知道 store name、key、默认值和异常处理细节。写到后面，所有页面都会变成半个仓储层。

EntryAbility 决定继续播种还是进入恢复页

页面只消费结果、展示状态、触发动作。跨页面刷新用轻量信号，完整业务对象继续由 Service 重新读取。

classEntryBootstrap{asyncrun(context:UIAbilityContext,windowStage:window.WindowStage):Promise<void>{constprobe=awaitnewStartupResourceProbe().checkDefaultDeck(context.resourceManager);awaitStartupLedgerRepository.saveProbeResult(probe);if(probe.status!=='ready'&&probe.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-n"PreferencesStore|AppStorage.setOrCreate|Repository|Service"D:\\ProgramData\\huawei\\lesson\\The_Book_of_Answers\nrg-n"question|answerText|deckName|hilog"D:\\ProgramData\\huawei\\lesson\\The_Book_of_Answers

常见问题与处理

处理这些问题时不要先改 UI 文案。先确认写入 owner、读取 owner 和刷新信号是否一致，再看页面是否正确消费结果。若只在页面补一个 Toast，用户当次可能看到了提示，但重启、返回、跨入口和发布复查仍然会暴露同一个根因。

落地取舍

这套方案不是为了把轻量应用写重，而是为了把真正会跨页面、跨启动、跨发布阶段的事实收住。只影响当前展示节奏的变量可以留在页面；会改变用户内容、持久结构、隐私口径或发布证据的逻辑，必须进入 Service、Repository 或发布清单。

真正落地时，可以先从一条最容易复现的路径开始：找出唯一写入点，补上结果模型，再把页面里的直接读写替换成 Service 调用。这个顺序比一次性重构全部页面更稳，也更容易在评审时说明每一行代码解决了哪个故障链。评审记录里最好保留对应的命令、截图或复现步骤，避免方案只停留在口头约定。

小结

启动预检的价值是把资源问题变成可解释状态。它不应该替代 SeedLoader，也不应该扫描整包；只要能在首屏前识别阻断资源，并给恢复页留下证据，就足够解决“资源缺失却表现成白屏”的排障断点。
更容易在评审时说明每一行代码解决了哪个故障链。评审记录里最好保留对应的命令、截图或复现步骤，避免方案只停留在口头约定。

小结

启动预检的价值是把资源问题变成可解释状态。它不应该替代 SeedLoader，也不应该扫描整包；只要能在首屏前识别阻断资源，并给恢复页留下证据，就足够解决“资源缺失却表现成白屏”的排障断点。