16-首屏卡在启动页-把初始化任务分级放到可控链路
第16篇｜首屏卡在启动页：把初始化任务分级放到可控链路
摘要：首屏卡住通常不是某个动画慢，而是把太多初始化任务塞进了 AbilityStage、WindowStage 或启动页。要让首屏稳定，先把启动任务分级：首屏前只跑必需任务，首屏后补缓存和诊断，所有任务都能记录阶段和失败原因。
我遇到过一个应用首次启动一直停在启动页，日志里没有明显异常。后来发现启动页在等用户信息、课程缓存、远端配置和诊断上传全部完成。真正应该挡住首屏的只有本地状态水合和会话判断，其余任务都可以后移。
这篇文章会把问题拆成几个可落地的点：
- 给启动任务分级，区分首屏前和首屏后。
- 让 AbilityStage、WindowStage 和 SplashPage 各做自己的事。
- 给每个初始化任务留下阶段标记和失败原因。
- 用清空数据、慢网和首次启动路径验证首屏不再被非关键任务卡住。
适用环境和边界
本文讨论 Stage 模型下应用启动链路，重点是 AbilityStage、UIAbility、WindowStage、启动页和初始化任务调度。示例不绑定具体业务，适合课程、工具、内容类应用的首屏治理。
| 维度 | 建议边界 |
|---|---|
| 首屏前 | 本地状态水合、会话判断、必要路由准备 |
| 首屏后 | 缓存预热、远端配置、诊断上传、非关键统计 |
| 页面职责 | 启动页展示进度并进入首页，不承载所有初始化 |
| 验证方式 | 首次安装、清空数据、慢网、离线和重启 |
| 不展开内容 | 不讨论复杂性能 profiling，只处理启动任务分级 |
启动链路最怕把所有任务都叫“初始化”。先分级，才能知道哪些必须挡住首屏，哪些应该延后。
先把故障链路复盘出来
首屏卡住时，不要先改动画。先看是窗口没加载、启动页没跳转，还是某个非关键任务一直没返回。
| 阶段 | 表面现象 | 更深的原因 | 应该看到的结果 |
|---|---|---|---|
| AbilityStage | 应用刚启动就停住 | 同步任务过重或阻塞 | 只做轻量水合 |
| WindowStage | 窗口创建后没有内容 | loadContent 失败或回调没记录 | 可见页面先加载出来 |
| SplashPage | 一直留在启动页 | 等待了缓存、网络和上传等非关键任务 | 只等待 required 任务 |
| 后置任务 | 首页已进但继续卡顿 | 后置任务和首屏抢资源 | 分阶段调度并记录耗时 |
把启动拆成阶段以后，排查就能从“卡住了”变成“卡在 load-session 还是 warm-cache”。这比继续加 loading 文案有用。
先定 owner，再写代码
启动 owner 要清楚。Ability 管生命周期，启动页管可见过渡，调度器管任务顺序，业务服务只提供自己的初始化函数。
| 对象 | 归属 | 不要越界做的事 |
|---|---|---|
| AbilityStage | 轻量水合和全局标记 | 发网络请求或解析大文件 |
| WindowStage | 加载首个页面并记录失败 | 等待业务缓存完成 |
| SplashPage | 等待 required 后跳首页 | 吞掉所有后置任务 |
| StartupScheduler | 按阶段运行任务 | 直接操作页面状态 |
| StartupReporter | 记录阶段和失败原因 | 承载业务逻辑 |
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 是否属于首屏前必需任务。
验证路径要覆盖真实操作
启动链路必须按首次安装路径验证。
- 清空应用数据后启动，确认首屏能进入首页。
- 断网启动，确认非关键网络任务不会卡住首屏。
- 模拟缓存为空，确认后置预热失败不影响主页面。
- 查看阶段标记，确认能定位每个 required 任务。
- 重启应用，确认不会重复执行昂贵任务。
- 执行
hvigorw assembleHap --no-daemon，确认示例改法没有破坏构建。
这组验证不要只在一个入口上跑。很多问题在主流程里看不出来，切换页面、返回、清空数据、改主题、断网、换宽屏后才会暴露。
风险和回退方案
| 风险 | 触发场景 | 处理方式 |
|---|---|---|
| 把任务全后移 | 首屏缺少会话或默认值 | required 只保留安全必需项 |
| 后置任务抢资源 | 首页刚出现又卡顿 | 分批执行并记录耗时 |
| 失败被吞掉 | 启动页无原因停住 | Reporter 记录失败阶段 |
| 状态未水合 | @StorageLink 首次读取 undefined | 启动前 setOrCreate 默认值 |
回退方案的价值不是保守，而是让一次修复能分阶段落地。先保住主路径，再删除旧逻辑，排查时才不会把多个变量混在一起。
常见问题和处理方式
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 启动页一直转 | 等待了非关键网络任务 | 拆成 required 和 afterFirstFrame |
| 首页进入后旧状态闪现 | 默认值未水合 | AbilityStage 先 setOrCreate |
| 真机偶现卡住 | 某个任务无超时或无标记 | 给任务加阶段记录和失败返回 |
| 关闭再开仍慢 | 每次重复预热重任务 | 按缓存版本决定是否执行 |
这些问题看起来分散，本质上都和 owner、状态来源、刷新时机和验证范围有关。只修一个按钮通常不够，要让同一类路径都走回同一套规则。
这次问题给我的复盘
启动优化不是把代码藏到别的生命周期里，而是把任务分级。首屏前保证安全默认值和会话判断，首屏后再补缓存、配置和诊断。
复盘这类问题时，我会先把用户看到的现象落到工程 owner 上，再看代码是不是沿着同一条边界走。只要 owner 不清，后面就会变成谁顺手谁修；owner 清楚以后，验证也能回到具体路径，而不是靠感觉判断。
真正落到项目里，我会用这份小清单收尾：
- 先把用户看到的现象对应到具体 owner，避免只改表面 UI。
- 再确认写入、读取、刷新、路由或资源是否沿着同一条链路。
- 搜索旧入口、旧 key、硬编码值或临时输出，能解释的保留，解释不通的收口。
- 用真实入口走一遍主路径，再补空态、失败态、返回、重启或宽屏路径。
- 把剩余风险写清楚，下一次维护时就不用重新猜当时为什么这么改。
小结：首屏先可用，再补齐能力
启动优化不是把代码藏到别的生命周期里，而是把任务分级。首屏前保证安全默认值和会话判断，首屏后再补缓存、配置和诊断。 这类问题最终都要回到 owner、代码边界和真实路径验证，不能只看某个片段是否写得顺眼。
搜索旧入口、旧 key、硬编码值或临时输出，能解释的保留，解释不通的收口。
4. 用真实入口走一遍主路径，再补空态、失败态、返回、重启或宽屏路径。
5. 把剩余风险写清楚，下一次维护时就不用重新猜当时为什么这么改。
小结：首屏先可用，再补齐能力
启动优化不是把代码藏到别的生命周期里，而是把任务分级。首屏前保证安全默认值和会话判断，首屏后再补缓存、配置和诊断。 这类问题最终都要回到 owner、代码边界和真实路径验证，不能只看某个片段是否写得顺眼。