页面能打开，不代表启动链设计得对。真正复杂的 HarmonyOS 应用，一旦同时存在通知拉起、桌面入口、快捷任务、深链和应用内部跳转，最容易失控的不是 UI，而是“这次启动从哪里来、该初始化什么、最终要去哪里”。

一、应用入口一多，最先乱掉的往往不是路由，而是初始化

小项目里通常只有一种启动方式：用户点图标，进入首页。

这种情况下，初始化写在哪里都好像能工作。比如页面 aboutToAppear() 里初始化数据库、加载配置、注册服务，短期看没有问题。

但项目一旦出现多个入口，问题马上开始放大：

• 系统通知点进来，需要直接进入详情页；
• 桌面快捷入口要进入一个特定任务；
• 应用内部点击卡片，同样要进入详情；
• 某些后台动作完成后，要通过 WantAgent 再次拉起指定能力；
• 热启动时，很多初始化又不应该重复执行。

这时候如果所有逻辑还散在页面里，就很容易出现两个典型问题。

第一个是重复初始化。数据库、SDK、路由表、缓存恢复，每个入口各执行一遍。

第二个是入口逻辑不一致。通知传的是 taskId，内部跳转传的是 id，快捷入口又用另一个字段。页面里充满兼容判断。

我后来把这个问题拆成两层：AbilityStage 负责应用级初始化，RouteService + WantAgent 负责入口统一和任务分发。

这篇文章就是把这两层怎么配合讲清楚。

二、AbilityStage 最适合承接“进程级只做一次”的工作

我以前很容易把 AbilityStage 当成一个生命周期概念，真正开始做复杂入口以后才发现，它最大的工程价值是“能把进程级初始化从页面里拿出去”。

我给它安排的工作一般有这些：

• 初始化全局配置；
• 建立日志系统；
• 初始化路由规则；
• 创建全局依赖容器；
• 做只需要执行一次的轻量恢复。

而页面数据加载、当前任务查询、界面状态，不放在这里。

核心结构我会写成这样：

import { AbilityStage } from '@kit.AbilityKit'

export default class AppStage extends AbilityStage {
  onCreate(): void {
    Logger.init()
    RouteService.init(this.context)
    AppConfig.load(this.context)

    Logger.info('AbilityStage onCreate')
  }
}

这段代码本身很短，但它建立了一个特别重要的边界：只和应用进程有关的初始化，才放这里。

不要因为 AbilityStage 很早执行，就把什么都塞进去。初始化太重一样会拖慢启动，甚至让真正的业务入口变得不透明。

三、入口统一的关键，不是“都跳同一个页面”，而是“都进同一个路由层”

多入口应用经常会走向另一个极端：为了统一，把所有入口都先打开首页，然后首页再判断参数跳转。

这确实能跑，但问题也很明显。用户点通知想看一条任务，结果先闪一下首页，再进详情；而且首页承担了本不该属于它的路由职责。

我的做法是先定义统一启动上下文：

export type LaunchContext = {
  source: 'launcher' | 'notification' | 'shortcut' | 'inner'
  target: string
  taskId?: string
  timestamp: number
  extras?: Record<string, Object>
}

无论来源是什么，都先转换成 LaunchContext，然后再交给 RouteService 做目标解析。

这样通知入口和内部跳转虽然来源不同，但后面的逻辑是同一条：

入口参数 → 标准启动上下文 → 路由规则 → 目标能力 → 页面参数

这个收口特别值。后面你要改详情页能力名，或者给某类任务增加中间校验，不需要去通知代码、快捷入口、首页按钮里各改一遍。

四、WantAgent 真正适合解决的是“未来某个时刻再执行一次目标动作”

WantAgent 很容易被理解成“另一种页面跳转”。

我实际用下来，更愿意把它理解成可交给系统或其他能力保存、以后再执行的目标动作描述。

比如：

• 通知点击以后启动指定能力；
• 某个延迟任务完成后回到结果页；
• 快捷入口带参数启动详情；
• 系统组件触发以后恢复应用任务。

我会单独封装一个创建方法，不在业务页面里直接拼参数：

import { wantAgent } from '@kit.AbilityKit'

async function createRouteAgent(target: string, taskId: string) {
  const info: wantAgent.WantAgentInfo = {
    wants: [{
      bundleName: 'com.demo.router',
      abilityName: target,
      parameters: {
        source: 'notification',
        taskId: taskId
      }
    }],
    operationType: wantAgent.OperationType.START_ABILITY,
    requestCode: buildRequestCode(taskId)
  }

  return await wantAgent.getWantAgent(info)
}

这里我最关心的不是“能不能创建成功”，而是两个工程问题。

第一，requestCode 要有稳定策略。如果所有任务都用同一个 requestCode，后面很容易出现新任务把旧任务语义覆盖的问题。

第二，参数命名必须和路由层统一。不要一边用 taskId，另一边临时改成 itemId。这种小差异在多入口项目里特别难排查。

五、冷启动和热启动，不能共用同一套初始化判断

很多生命周期问题的根源，是代码默认“每次启动都一样”。

但冷启动和热启动根本不是一回事。

冷启动时，进程刚创建，AbilityStage 需要初始化；UIAbility 需要创建；WindowStage 也要建立。

热启动时，进程可能一直在，AbilityStage 根本不需要重新初始化，真正需要做的只是处理新的 Want、更新页面数据、切到正确任务。

所以我的原则是：

• 进程级能力看 AbilityStage；
• 新入口参数看 UIAbility 收到的 Want；
• 页面展示看当前路由结果；
• 不用“页面重新出现”代替“应用重新初始化”。

这一点在有后台任务和通知入口的应用里特别重要。否则一个通知点进来，数据库、日志、缓存全重新初始化一遍，既浪费时间，也更容易产生状态覆盖。

六、生命周期日志必须带“来源”和“目标”，否则看不出问题

普通页面开发里，日志写一句 onCreate 可能就够了。

多入口应用不够。

我最后会记录至少四类信息：

• 生命周期节点；
• 当前入口来源；
• 解析后的目标能力；
• 关键参数和耗时。

比如一次通知冷启动，我希望日志最终能串成这样：

09:43:58.012 AbilityStage.onCreate
09:43:58.041 EntryAbility.onCreate source=notification
09:43:58.086 onWindowStageCreate
09:43:58.131 RouteService.resolve target=DetailAbility
09:43:58.158 WantAgent.trigger requestCode=1001
09:43:58.201 onForeground taskId=1024

这类日志有一个巨大好处：用户说“我点通知进去页面不对”，你不需要猜到底是通知没传参数、路由没匹配、WantAgent 目标错了，还是页面没刷新。

顺着链看，很快就能定位。

七、DevEco 联调时，我会故意模拟三种启动方式

只用桌面图标启动测试，几乎看不出多入口设计的问题。

所以我在开发阶段通常会至少模拟三种情况：

1. 正常桌面冷启动；
2. 应用已经在前台时再次收到入口；
3. 应用在后台或进程恢复时，通过外部入口进入特定任务。

调试时重点看：

• AbilityStage 有没有重复执行；
• RouteService 是否在每次新入口时都重新解析参数；
• WantAgent 的 requestCode 是否符合预期；
• 目标页面有没有拿到最新参数；
• 热启动有没有误走冷启动逻辑。

如果这五个点能稳定，整个启动链基本就站住了。

八、这类架构最常见的几个坑

第一个坑，把所有初始化都塞 AbilityStage。它是应用级入口，不代表适合执行一切任务。耗时初始化仍然要拆分、延迟或者按需执行。

第二个坑，路由逻辑散在页面和通知代码里。入口越多，重复越严重。最好统一收口到 RouteService。

第三个坑，用页面生命周期猜启动来源。页面只知道自己出现了，不一定知道为什么出现。来源应该来自明确的启动上下文。

第四个坑，WantAgent 的参数没有版本意识。如果后续参数结构变化，旧通知或旧快捷入口可能仍然存在，最好给参数留版本或兼容策略。

第五个坑，热启动没有做参数去重。短时间重复触发同一个任务，可能连续打开多次详情或重复执行同一个动作。路由层应该有基本的幂等判断。

九、把启动链收口以后，页面代码会明显变干净

这次做完以后，最明显的变化不是“生命周期更高级了”，而是页面里少了很多原本不该存在的代码。

页面不再关心：

• 我是从通知来的还是桌面来的；
• 这次是不是冷启动；
• WantAgent 是谁创建的；
• requestCode 应该是多少；
• 全局服务有没有初始化过。

它只拿一个已经解析好的页面参数，然后展示内容。

这就是我认为这套结构真正的价值：不是为了多一层架构，而是为了让每一层只处理自己该处理的事情。

十、本文小记

AbilityStage、UIAbility、WantAgent 单独看都不复杂，真正到了工程里，难的是把它们放在正确的位置。

我的最终判断是：

• AbilityStage 管进程级一次性初始化；
• RouteService 管入口标准化和目标解析；
• WantAgent 管可延后执行的目标动作；
• 页面只消费解析后的业务参数。

这四层一旦分开，多入口应用的生命周期就会清楚很多。

如果让我给这篇文章留一句结论，我会写：不要让页面替应用管理启动链。

当入口越来越多时，真正需要治理的不是页面数量，而是初始化、路由和生命周期之间的边界。