HarmonyOS 7.0 / API 26 AppStartup 启动画像实战：首屏任务怎么分级下沉

这篇只拆一个具体点：AppStartup 启动画像、首屏任务分级和冷启动性能治理。版本边界先放前面：下面的写法面向 HarmonyOS 7.0 / API 26。工程里如果还在混用旧 SDK、旧模拟器镜像或旧设备系统，先不要直接照搬代码，先把版本对齐。

这个问题为什么值得单独拆

启动优化不能只看总耗时。真正影响用户感受的是首屏前塞了多少同步任务、哪些任务可以延后、哪些任务必须等首屏后再跑。HarmonyOS 7.0 / API 26 场景下，多设备、多窗口和新能力初始化更多，如果不做启动画像，很容易把首屏拖慢。

这类问题的麻烦点是：代码经常能编译，页面第一次打开也像是正常的，但一到折叠屏、多窗口、后台恢复、跨设备入口或审核机型上，行为就开始不稳定。我的处理方式不是先改 UI，而是先把能力边界、触发条件、失败原因和兜底方案拆开。

先对齐官方能力边界

这里要避免一个常见误区：看到 7.0 新能力就直接在页面里调用。更稳的做法是先做一层能力判断，判断通过再进入新能力分支，判断失败就明确走兜底，日志里也要能看出失败原因。

两个容易复现的场景

场景一：冷启动时同时初始化网络、数据库、图片缓存和能力探测

复现方式不要做得太复杂。先把页面打开到目标状态，再连续触发两次能力入口。这个时候重点看三个点：状态有没有丢、资源有没有重复申请、失败时有没有明确原因。

场景二：平板分屏恢复后把非首屏任务又跑了一遍

第二个场景更接近线上：用户不会按开发者预设路径操作，他会切后台、恢复、换方向、分屏、拖拽、锁屏再回来。只看单次点击，问题很容易被遮住。

拆法：先决策，再执行，再兜底

我会把实现拆成三层：

1. 能力判断层：只判断版本、设备形态、入口参数和依赖状态。
2. 执行层：只负责调用具体 API，不混入页面展示逻辑。
3. 兜底层：能力不可用时给旧方案、提示或延迟重试，不让页面进入半坏状态。

这样拆的好处是后面升级 SDK 或换设备时，不需要在每个页面里翻 if 判断。页面只拿一个明确结果：能用、不能用、为什么不能用。

Demo：把能力判断收口到一个 guard

type StartupPriority = 'must' | 'afterFirstFrame' | 'idle';

interface StartupTask {
  name: string;
  priority: StartupPriority;
  maxCostMs: number;
  run: () => Promise<void>;
}

interface StartupResult {
  name: string;
  priority: StartupPriority;
  costMs: number;
  status: 'passed' | 'fallback';
  reason: string;
}

class StartupProfiler {
  async runBeforeFirstFrame(tasks: StartupTask[]): Promise<StartupResult[]> {
    const results: StartupResult[] = [];
    for (const task of tasks.filter(item => item.priority === 'must')) {
      const start = Date.now();
      try {
        await task.run();
        results.push({ name: task.name, priority: task.priority, costMs: Date.now() - start, status: 'passed', reason: 'must-task-finished' });
      } catch (err) {
        results.push({ name: task.name, priority: task.priority, costMs: Date.now() - start, status: 'fallback', reason: String(err) });
      }
    }
    return results;
  }

  collectDeferred(tasks: StartupTask[]): StartupTask[] {
    return tasks.filter(item => item.priority !== 'must');
  }
}

async function noopTask(): Promise<void> {
  return;
}

const tasks: StartupTask[] = [
  { name: 'read-local-config', priority: 'must', maxCostMs: 20, run: noopTask },
  { name: 'layout-breakpoint', priority: 'must', maxCostMs: 30, run: noopTask },
  { name: 'image-cache-warmup', priority: 'afterFirstFrame', maxCostMs: 120, run: noopTask },
  { name: 'capability-probe', priority: 'idle', maxCostMs: 200, run: noopTask },
];

const profiler = new StartupProfiler();
profiler.runBeforeFirstFrame(tasks).then(result => {
  console.info('[startup]', JSON.stringify(result));
});

这个 Demo 只做一件事：先判断能力条件，再把结果交给页面。页面不直接关心 API 细节，也不把版本判断散落在 build 里。后面要接真实页面时，可以把 HarmonyFeatureGuard 放到公共模块里复用。

异常日志应该长什么样

[startup] stage=abilityCreate, task=sdk-check, priority=must, cost=8ms
[startup] stage=firstFrame, task=image-cache-warmup, priority=defer, cost=0ms
[startup] stage=afterFirstFrame, task=capability-probe, cost=36ms
[startup] status=passed, firstFrameCost=412ms

日志不要只打印“失败了”。至少要带上 scene、status、reason 和耗时。否则出了问题以后，只能靠猜。

验证矩阵

跑完后应该看到的结果

case: cold_start_budget -> passed
case: resume_skip_cold_tasks -> passed
case: capability_probe_timeout_fallback -> passed
case: foldable_layout_before_prefetch -> passed

我会怎么选方案

我的选择是第三种。只要这个能力会被多个页面用到，就不要把判断逻辑塞在页面里。页面只负责展示，能力边界、异常兜底、版本判断放到独立函数或组件里。这样后面改 SDK、换设备、补兼容逻辑，影响面会小很多。

排查顺序

1. 先打启动阶段日志，别先凭感觉删初始化代码。
2. 再按 must、afterFirstFrame、idle 三档给任务分级。
3. 遇到超时任务先降级，不要让它卡住首屏。
4. 把启动画像结果放进发版前自检，避免只在自己电脑上看起来流畅。

可以怎么复用

这个写法可以继续扩成一个小工具：输入 featureName、apiLevel、deviceMode、entryState，输出 passed / failed / fallback 和 reason。页面层只根据结果更新 UI。这样做虽然前期多写几行代码，但后面接更多 HarmonyOS 7.0 能力时，判断逻辑不会越写越散。

最后总结

AppStartup 启动画像要把首屏前任务、首屏后任务、可延迟任务和可取消任务分清楚，再用日志和预算表验证优化是否真的有效。

这类特性真正有价值的地方，不是知道一个新名字，而是知道它在什么场景该用、什么时候不该用、怎么复现问题、怎么把修复沉淀成可复用代码。后面再接复杂页面时，先把这个小 Demo 跑通，基本能避开一半低级返工。

可收藏的启动任务分级表

这类优化最怕只写“异步加载”。真正有效的是把任务放到正确阶段，并且每个阶段都有日志证据。