16-首屏卡在启动页-把初始化任务分级放到可控链路

第16篇｜首屏卡在启动页：把初始化任务分级放到可控链路

摘要：首屏卡住通常不是某个动画慢，而是把太多初始化任务塞进了 AbilityStage、WindowStage 或启动页。要让首屏稳定，先把启动任务分级：首屏前只跑必需任务，首屏后补缓存和诊断，所有任务都能记录阶段和失败原因。

我遇到过一个应用首次启动一直停在启动页，日志里没有明显异常。后来发现启动页在等用户信息、课程缓存、远端配置和诊断上传全部完成。真正应该挡住首屏的只有本地状态水合和会话判断，其余任务都可以后移。

这篇文章会把问题拆成几个可落地的点：

1. 给启动任务分级，区分首屏前和首屏后。
2. 让 AbilityStage、WindowStage 和 SplashPage 各做自己的事。
3. 给每个初始化任务留下阶段标记和失败原因。
4. 用清空数据、慢网和首次启动路径验证首屏不再被非关键任务卡住。

适用环境和边界

本文讨论 Stage 模型下应用启动链路，重点是 AbilityStage、UIAbility、WindowStage、启动页和初始化任务调度。示例不绑定具体业务，适合课程、工具、内容类应用的首屏治理。

启动链路最怕把所有任务都叫“初始化”。先分级，才能知道哪些必须挡住首屏，哪些应该延后。

先把故障链路复盘出来

首屏卡住时，不要先改动画。先看是窗口没加载、启动页没跳转，还是某个非关键任务一直没返回。

把启动拆成阶段以后，排查就能从“卡住了”变成“卡在 load-session 还是 warm-cache”。这比继续加 loading 文案有用。

先定 owner，再写代码

启动 owner 要清楚。Ability 管生命周期，启动页管可见过渡，调度器管任务顺序，业务服务只提供自己的初始化函数。

owner 清楚后，启动优化就不是把代码从一个生命周期挪到另一个生命周期，而是让任务在正确阶段执行。

先列启动任务账本

启动链路里，这一步要回答一个问题：它是否必须挡住首屏。如果不是，就应该后移或单独记录。

exportinterfaceStartupTask{name:stringlevel:'required'|'afterFirstFrame'|'idle'run():Promise<void>}exportconstStartupTasks:StartupTask[]=[{name:'hydrate-storage',level:'required',run:hydrateStorage},{name:'load-session',level:'required',run:loadSession},{name:'warm-course-cache',level:'afterFirstFrame',run:warmCourseCache},{name:'upload-diagnostics',level:'idle',run:uploadDiagnostics}]

启动任务先分级，首屏前只放真正影响页面安全的任务。缓存预热和诊断上传不应该挡住首屏。

AbilityStage 只做轻量准备

启动链路里，这一步要回答一个问题：它是否必须挡住首屏。如果不是，就应该后移或单独记录。

exportclassAppAbilityStageextendsAbilityStage{onCreate():void{hydrateStorage()StartupReporter.mark('ability-stage-created')}}

AbilityStage 适合做极轻量、必须的初始化。不要把网络请求、缓存预热和大文件解析塞在这里。

WindowStage 先加载可用页面

启动链路里，这一步要回答一个问题：它是否必须挡住首屏。如果不是，就应该后移或单独记录。

exportclassEntryAbilityextendsUIAbility{onWindowStageCreate(windowStage:window.WindowStage):void{windowStage.loadContent('pages/SplashPage',(err)=>{if(err.code){StartupReporter.fail('load-content',`${err.code}`)}})}}

窗口创建阶段优先把可见页面加载出来。首屏能展示以后，再让页面或调度器继续跑非关键任务。

调度器按阶段执行

启动链路里，这一步要回答一个问题：它是否必须挡住首屏。如果不是，就应该后移或单独记录。

exportclassStartupScheduler{asyncrun(level:StartupTask['level']):Promise<void>{consttasks=StartupTasks.filter((item)=>item.level===level)for(consttaskoftasks){awaittask.run()StartupReporter.mark(task.name)}}}

串行执行便于定位卡在哪个任务。任务很多时可以再并发，但先有账本和阶段比直接 Promise.all 更可靠。

页面只等待必需状态

启动链路里，这一步要回答一个问题：它是否必须挡住首屏。如果不是，就应该后移或单独记录。

@Entry@Componentstruct SplashPage{@Stateready:boolean=falseprivatescheduler:StartupScheduler=createStartupScheduler()asyncaboutToAppear():Promise<void>{awaitthis.scheduler.run('required')this.ready=truethis.openHome()this.scheduler.run('afterFirstFrame')}}

Splash 只等待 required 任务。进入首页后再补后置任务，首屏就不会因为非关键初始化卡住。

启动耗时要留下阶段标记

启动链路里，这一步要回答一个问题：它是否必须挡住首屏。如果不是，就应该后移或单独记录。

exportclassStartupReporter{privatestaticmarks:string[]=[]staticmark(name:string):void{this.marks.push(`${Date.now()}:${name}`)}staticfail(name:string,reason:string):void{this.marks.push(`${Date.now()}:${name}:${reason}`)}}

启动问题最怕只知道卡住，不知道卡在哪。阶段标记能帮助定位是水合、会话、页面加载还是后置任务。

用反向搜索把旧路径清掉

启动问题改完后，重点找阻塞任务、同步大计算和散落的启动入口。

rg"AbilityStage|onWindowStageCreate|loadContent|SplashPage"entry features common rg"Promise.all|await .*Cache|warm|upload|diagnostics|setTimeout"entry features common rg"setOrCreate|AppStorage|StartupTask|StartupScheduler"entry features common

搜索不是为了删掉所有 await，而是确认每个 await 是否属于首屏前必需任务。

验证路径要覆盖真实操作

启动链路必须按首次安装路径验证。

1. 清空应用数据后启动，确认首屏能进入首页。
2. 断网启动，确认非关键网络任务不会卡住首屏。
3. 模拟缓存为空，确认后置预热失败不影响主页面。
4. 查看阶段标记，确认能定位每个 required 任务。
5. 重启应用，确认不会重复执行昂贵任务。
6. 执行hvigorw assembleHap --no-daemon，确认示例改法没有破坏构建。

这组验证不要只在一个入口上跑。很多问题在主流程里看不出来，切换页面、返回、清空数据、改主题、断网、换宽屏后才会暴露。

风险和回退方案

回退方案的价值不是保守，而是让一次修复能分阶段落地。先保住主路径，再删除旧逻辑，排查时才不会把多个变量混在一起。

常见问题和处理方式

这些问题看起来分散，本质上都和 owner、状态来源、刷新时机和验证范围有关。只修一个按钮通常不够，要让同一类路径都走回同一套规则。

这次问题给我的复盘

启动优化不是把代码藏到别的生命周期里，而是把任务分级。首屏前保证安全默认值和会话判断，首屏后再补缓存、配置和诊断。

复盘这类问题时，我会先把用户看到的现象落到工程 owner 上，再看代码是不是沿着同一条边界走。只要 owner 不清，后面就会变成谁顺手谁修；owner 清楚以后，验证也能回到具体路径，而不是靠感觉判断。

真正落到项目里，我会用这份小清单收尾：

1. 先把用户看到的现象对应到具体 owner，避免只改表面 UI。
2. 再确认写入、读取、刷新、路由或资源是否沿着同一条链路。
3. 搜索旧入口、旧 key、硬编码值或临时输出，能解释的保留，解释不通的收口。
4. 用真实入口走一遍主路径，再补空态、失败态、返回、重启或宽屏路径。
5. 把剩余风险写清楚，下一次维护时就不用重新猜当时为什么这么改。

小结：首屏先可用，再补齐能力

启动优化不是把代码藏到别的生命周期里，而是把任务分级。首屏前保证安全默认值和会话判断，首屏后再补缓存、配置和诊断。 这类问题最终都要回到 owner、代码边界和真实路径验证，不能只看某个片段是否写得顺眼。
搜索旧入口、旧 key、硬编码值或临时输出，能解释的保留，解释不通的收口。
4. 用真实入口走一遍主路径，再补空态、失败态、返回、重启或宽屏路径。
5. 把剩余风险写清楚，下一次维护时就不用重新猜当时为什么这么改。

小结：首屏先可用，再补齐能力

启动优化不是把代码藏到别的生命周期里，而是把任务分级。首屏前保证安全默认值和会话判断，首屏后再补缓存、配置和诊断。 这类问题最终都要回到 owner、代码边界和真实路径验证，不能只看某个片段是否写得顺眼。