HarmonyOS AbilityStage 实战：别把启动参数散落在每个页面里

鸿蒙应用做到后面，真正让人头疼的，往往不是某个页面写得丑，也不是某个按钮样式没调好，而是入口越来越多以后，启动逻辑开始乱。

桌面图标能进来，服务卡片能进来，通知能进来，Deep Link 能进来，应用内部还可能用 Want 拉起另一个 UIAbility。第一版代码一般都挺朴素：在首页 aboutToAppear 里读一下参数，判断要不要跳详情页。刚开始没问题，甚至看起来挺清爽。

但需求一多，首页就很容易变成"入口垃圾桶"。

这里判断通知来源，那里判断服务卡片参数，后面又补一个外部链接解析。冷启动的时候还能凑合，二次拉起、回前台、横竖屏切换、任务栈恢复一来，问题就开始变得有点玄学了。

我之前见过一个挺典型的线上问题：用户从服务卡片点进来，本来应该打开某个订单详情页，结果偶尔落到首页；用户从外部链接再次拉起应用，页面没刷新；还有更隐蔽的，应用已经在后台了，新的 Want 进来以后，全局初始化又跑了一遍，监听注册了两次，后面同一个事件回调两遍。

查日志的时候也挺难受。每个页面都觉得自己只是"顺手处理一下入口参数"，最后谁也说不清这次启动到底是桌面启动、卡片启动，还是二次拉起。

这种问题不能靠再加几个 if 硬顶。Stage 模型下，AbilityStage、Want、UIAbility 这条链路本来就应该承担启动治理的职责。只是很多项目写着写着，把它们当成了"系统自动生成的模板文件"，真正的业务入口反而全塞到页面里了。

AbilityStage / Want / UIAbility，别分开看

单独看这几个概念，其实都不复杂。

AbilityStage 是 Module 级别的组件管理器，HAP 首次加载时会创建它。UIAbility 是带界面的应用组件，负责创建、销毁、前后台切换这些生命周期。Want 是组件之间传递信息的载体，启动目标、参数、action、uri 这些东西都可以从里面拿。

但工程里真正容易出问题的地方，不是"某个回调怎么写"，而是边界没划清。

我一般会这么分：

• AbilityStage 管进程级、模块级的东西，比如轻量初始化、Specified 启动模式分流、全局依赖准备。
• Want 只当入口信息，进来以后尽快转成业务能理解的结构。
• UIAbility 管窗口、生命周期和启动载荷注入。
• ArkUI 页面只消费归一后的业务参数，不直接解析原始 Want。

这几条边界看着有点啰嗦，但真到项目里很有用。

后面新增通知入口、服务卡片入口、Deep Link 入口时，不需要每个页面跟着改。入口逻辑集中在入口层，页面只关心"我要展示什么业务状态"。这才比较像一个能长期维护的结构。

先把原始 Want 收敛成 LaunchPayload

很多启动混乱，根源就是页面直接读 Want。

页面一旦开始知道太多入口细节，就会慢慢变成半个路由中心。今天读 scene，明天读 from，后天再补一个 uri，最后首页里一堆参数判断，谁也不敢动。

我更习惯定义一个中间结构，叫 LaunchPayload。它不追求把 Want 的所有字段都复刻一遍，只留下业务真正需要的东西。

// common/launch/LaunchPayload.ets
export enum LaunchScene {
  NORMAL = 'normal',
  CARD = 'card',
  NOTIFICATION = 'notification',
  DEEP_LINK = 'deep_link',
  INTERNAL = 'internal'
}

export interface LaunchPayload {
  scene: LaunchScene
  targetPage: string
  bizId?: string
  uri?: string
  from?: string
  rawAction?: string
  extras: Record<string, string>
  receivedAt: number
}

这里有个小取舍：extras 我只放字符串。

不是说 Want 里不能带别的类型，而是启动参数最好别变成一个"万能对象"。入口传来的东西越杂，页面兜底越麻烦。真要复杂对象，建议传 id，再让业务层去查详情。

启动参数要负责的是"把用户带到哪"，不是"把整个业务现场都搬进来"。这句话挺重要，很多入口混乱都是从这里开始的。

写一个 Want 解析器，别让页面自己猜

下面这个 LaunchPayloadParser 就是专门干脏活的。

它负责把不同来源的 Want 参数，统一整理成业务可读的结构。页面拿到的不是一坨原始参数，而是一份已经归一过的启动载荷。

// common/launch/LaunchPayloadParser.ets
import { Want } from '@kit.AbilityKit'
import { LaunchPayload, LaunchScene } from './LaunchPayload'

export class LaunchPayloadParser {
  static parse(want: Want | undefined): LaunchPayload {
    const params = want?.parameters ?? {}
    const uri = want?.uri ?? ''
    const action = want?.action ?? ''

    const scene = this.parseScene(params, uri, action)
    const bizId = this.readString(params, 'bizId')
    const from = this.readString(params, 'from')

    return {
      scene,
      targetPage: this.resolveTargetPage(scene, bizId, uri),
      bizId,
      uri,
      from,
      rawAction: action,
      extras: this.pickSafeExtras(params),
      receivedAt: Date.now()
    }
  }

  private static parseScene(params: Record<string, Object>, uri: string, action: string): LaunchScene {
    const scene = this.readString(params, 'scene')

    if (scene === 'card') {
      return LaunchScene.CARD
    }

    if (scene === 'notification') {
      return LaunchScene.NOTIFICATION
    }

    if (uri.length > 0) {
      return LaunchScene.DEEP_LINK
    }

    if (action.length > 0) {
      return LaunchScene.INTERNAL
    }

    return LaunchScene.NORMAL
  }

  private static resolveTargetPage(scene: LaunchScene, bizId?: string, uri?: string): string {
    if (scene === LaunchScene.DEEP_LINK && uri) {
      return this.resolveDeepLink(uri)
    }

    if (bizId && bizId.length > 0) {
      return 'pages/Detail'
    }

    return 'pages/Home'
  }

  private static resolveDeepLink(uri: string): string {
    // 这里只做简单示例。
    // 真实项目里建议做白名单解析，别让外部 uri 任意指定页面路径。
    if (uri.includes('/detail')) {
      return 'pages/Detail'
    }

    if (uri.includes('/search')) {
      return 'pages/Search'
    }

    return 'pages/Home'
  }

  private static pickSafeExtras(params: Record<string, Object>): Record<string, string> {
    const allowList: string[] = ['tab', 'keyword', 'source']
    const extras: Record<string, string> = {}

    allowList.forEach((key: string) => {
      const value = this.readString(params, key)
      if (value !== undefined) {
        extras[key] = value
      }
    })

    return extras
  }

  private static readString(params: Record<string, Object>, key: string): string | undefined {
    const value = params[key]
    return typeof value === 'string' ? value : undefined
  }
}

这段代码看起来确实有点啰嗦，但它救命的地方也就在这。

所有入口先过一层白名单，不允许外部参数直接控制内部页面路径；所有参数先转成可控结构，不让页面到处写 want.parameters?.xxx。项目越大，这种"看起来多一层"的代码越值钱。

我自己比较怕那种"先凑合一下"的入口代码。因为入口一旦散了，后面不是不好重构，是没人敢重构。用户从哪里进来、带了什么参数、应该落到哪个页面，全都藏在几个页面生命周期里，查一次问题能把人查麻。

AbilityStage：只做进程级初始化和启动分流

AbilityStage 很容易被误用。

有些项目会把一堆业务初始化都丢进去：数据库、网络、埋点、用户信息、远程配置，全塞上。冷启动一慢，大家又开始怀疑系统回调慢，或者怀疑首屏性能不行。其实很多时候，是自己把太重的东西放错地方了。

我的建议比较保守：AbilityStage 只做轻量、必要、进程级的事情。

比如日志初始化、依赖容器准备、Specified 启动模式的 key 分流。需要 IO、需要用户态、需要网络的初始化，不要一股脑压在这里。

// entry/src/main/ets/entryability/MyAbilityStage.ets
import { AbilityStage, Want } from '@kit.AbilityKit'
import { hilog } from '@kit.PerformanceAnalysisKit'
import { LaunchPayloadParser } from '../common/launch/LaunchPayloadParser'

export default class MyAbilityStage extends AbilityStage {
  onCreate(): void {
    // 这里适合做轻量级、进程级准备。
    // 不建议在这里做耗时网络请求，也别依赖页面上下文。
    hilog.info(0x0000, 'AppStage', 'AbilityStage onCreate')
  }

  onAcceptWant(want: Want): string {
    // Specified 启动模式下，系统会通过这个 key 决定复用哪个 UIAbility 实例。
    // key 设计要稳定，不要把时间戳这种随机值塞进去。
    const payload = LaunchPayloadParser.parse(want)

    if (payload.bizId && payload.bizId.length > 0) {
      return `detail_${payload.bizId}`
    }

    return 'main'
  }
}

onAcceptWant 这块很容易写错。

我见过有人为了"保证每次都是新的"，直接返回时间戳。短期看，好像解决了页面不刷新的问题；长期看，其实是把实例复用搞乱了。

Specified 模式要的不是"每次都新开"，而是"同一类业务复用同一个目标实例"。key 的粒度要跟业务场景一致。比如详情页按 id 分流，主入口统一回到 main。别为了省事，把 key 写成一个随机数，那后面任务栈和实例管理都会跟着乱。

UIAbility：冷启动和二次拉起要走同一套逻辑

UIAbility 的生命周期更贴近业务。

用户冷启动时会走 onCreate，窗口创建时走 onWindowStageCreate；应用已有实例再次被拉起时，常见场景会走 onNewWant。如果只在 onCreate 里处理参数，二次拉起就很容易漏。

我一般会在 UIAbility 里保留一个当前启动载荷，然后用 LocalStorage 注入页面。页面不直接碰 Want。

// entry/src/main/ets/entryability/EntryAbility.ets
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'
import { window } from '@kit.ArkUI'
import { hilog } from '@kit.PerformanceAnalysisKit'
import { LaunchPayload } from '../common/launch/LaunchPayload'
import { LaunchPayloadParser } from '../common/launch/LaunchPayloadParser'

export default class EntryAbility extends UIAbility {
  private storage: LocalStorage = new LocalStorage()
  private latestPayload?: LaunchPayload

  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    this.latestPayload = LaunchPayloadParser.parse(want)
    this.storage.setOrCreate('launchPayload', this.latestPayload)

    hilog.info(0x0000, 'EntryAbility',
      `onCreate scene=${this.latestPayload.scene}, target=${this.latestPayload.targetPage}`)
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    // 页面首次加载时，把归一后的启动载荷注入进去。
    windowStage.loadContent('pages/Home', this.storage, (err) => {
      if (err.code) {
        hilog.error(0x0000, 'EntryAbility',
          `loadContent failed, code=${err.code}, message=${err.message}`)
        return
      }

      hilog.info(0x0000, 'EntryAbility', 'loadContent success')
    })
  }

  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 已有实例被再次拉起时，不要重复跑全局初始化。
    // 这里只更新启动载荷，让页面或路由层消费。
    this.latestPayload = LaunchPayloadParser.parse(want)
    this.storage.setOrCreate('launchPayload', this.latestPayload)

    hilog.info(0x0000, 'EntryAbility',
      `onNewWant scene=${this.latestPayload.scene}, target=${this.latestPayload.targetPage}`)
  }

  onForeground(): void {
    // 恢复轻量资源，例如刷新当前会话状态。
    // 不建议在这里重复解析启动参数。
    hilog.info(0x0000, 'EntryAbility', 'onForeground')
  }

  onBackground(): void {
    // 暂停耗时任务、保存必要状态。
    hilog.info(0x0000, 'EntryAbility', 'onBackground')
  }

  onDestroy(): void {
    // 取消监听、释放 UIAbility 级资源。
    hilog.info(0x0000, 'EntryAbility', 'onDestroy')
  }
}

这段的重点不是 loadContent，而是 onCreate 和 onNewWant 共用同一个解析器。

冷启动和二次拉起不应该分裂成两套业务规则。你今天忘了在 onNewWant 补一个参数，明天就会遇到那种特别烦的现象：应用杀掉后正常，后台唤起异常；从桌面进来正常，从通知进来异常。

这类问题通常不好测，因为测试同学一旦把应用杀掉重进，问题就消失了。

页面只消费 LaunchPayload，不碰原始 Want

页面里可以用 @LocalStorageProp 拿到启动载荷。至于它来自桌面、卡片还是 Deep Link，页面不需要知道太多。

// entry/src/main/ets/pages/Home.ets
import { LaunchPayload, LaunchScene } from '../common/launch/LaunchPayload'

@Entry
@Component
struct Home {
  @LocalStorageProp('launchPayload') launchPayload?: LaunchPayload

  @State tip: string = '正常进入首页'

  aboutToAppear(): void {
    this.consumeLaunchPayload(this.launchPayload)
  }

  onPageShow(): void {
    // 从后台回到前台时，页面可做轻量刷新。
    // 不建议在这里重新猜测启动来源。
  }

  private consumeLaunchPayload(payload?: LaunchPayload): void {
    if (!payload) {
      return
    }

    if (payload.scene === LaunchScene.CARD) {
      this.tip = `从服务卡片进入，业务ID：${payload.bizId ?? '无'}`
      return
    }

    if (payload.scene === LaunchScene.DEEP_LINK) {
      this.tip = `从外部链接进入：${payload.uri ?? ''}`
      return
    }

    if (payload.bizId) {
      this.tip = `准备打开详情：${payload.bizId}`
      return
    }

    this.tip = '正常进入首页'
  }

  build() {
    Column({ space: 16 }) {
      Text('HarmonyOS 启动治理示例')
        .fontSize(22)
        .fontWeight(FontWeight.Bold)

      Text(this.tip)
        .fontSize(15)
        .fontColor('#666666')

      if (this.launchPayload?.targetPage === 'pages/Detail') {
        Button('进入详情')
          .onClick(() => {
            // 项目里可以交给统一 RouterService，
            // 不建议在每个页面散落路由拼接。
          })
      }
    }
    .padding(24)
    .width('100%')
  }
}

这里有个问题经常有人问：为什么不在 UIAbility 里直接路由到详情页？

可以，但要看项目的路由方案。

如果你的登录态、弹窗恢复、页面栈管理、Tab 状态都在页面层或者 RouterService 里，UIAbility 直接跳详情页，有时候反而会绕过业务状态。我的做法是，UIAbility 负责把"启动意图"送到页面，真正的业务路由交给应用内部的 RouterService。

这样页面栈归页面，入口归入口，边界比较清楚。后面要改路由策略，也不用去生命周期回调里翻一堆代码。

生命周期不是背回调顺序，而是定职责

UIAbility 启动到前台时，会触发 onCreate()、onWindowStageCreate()、onForeground() 这一类生命周期回调。文档顺序看懂不难，难的是每个回调里该放什么、不该放什么。

我通常按下面这个口径拆：

onCreate：读取 Want，生成 LaunchPayload，准备 UIAbility 级状态。别在这里直接操作还没创建的窗口。

onWindowStageCreate：加载页面，注入 LocalStorage，绑定窗口相关逻辑。窗口级别的东西放这里，不要提前。

onNewWant：已有实例再次被拉起时更新启动意图。这里不要重复初始化全局服务，也不要重复注册监听。

onForeground：应用回到前台，恢复轻量资源，比如刷新会话、恢复播放按钮状态。不要把它当第二个 onCreate。

onBackground：暂停耗时任务，保存必要状态。能停的就停，尤其是轮询、定位、长连接这类逻辑。

onDestroy：取消监听、释放资源、打点收尾。不要假设它每次都一定按你期望的时机触发，但该写的清理还是要写。

职责分清以后，很多"偶发问题"就不再玄学了。

比如二次拉起没刷新，就去看 onNewWant；前后台切换重复初始化，就查 onForeground；窗口相关状态异常，就去看 onWindowStageCreate。至少排查方向是明确的，不至于在首页、详情页、路由工具类之间来回翻。

常见坑位：这些地方真的容易埋雷

1. 首页承担了太多入口职责

首页读 Want、首页解析 URI、首页判断通知、首页处理卡片参数，短期确实快，长期基本一定乱。首页是 UI，不是入口网关。

这个坑很多项目都会踩，因为第一版最方便的地方就是首页。但方便不是没有代价，只是代价晚点来。

2. onNewWant 忘了处理

这类 bug 很烦：冷启动正常，后台再次拉起异常；杀掉应用再试，又正常了。

原因往往是只在 onCreate 解析了 Want，已有实例二次拉起时没有更新业务载荷。开发自测时如果习惯每次都杀进程，很容易漏掉。

3. Specified key 设计太随意

onAcceptWant 返回的 key 应该稳定、有业务含义。

随机 key 会让实例复用不可控；key 粒度太粗，会导致不同业务入口抢同一个实例。这个地方别偷懒，最好一开始就按业务场景定规则。

4. 外部参数直接控制页面路径

Deep Link 或外部 Want 里带一个 path，然后你直接 router 到对应页面，这个写法很危险。

至少要做白名单映射。外部参数只能表达意图，不能拿到内部路由的完全控制权。尤其是对外开放的链接入口，更不能相信传进来的每一个字段。

5. 前后台切换重复初始化

onForeground 不是重启。

回前台时做轻量恢复可以，别把登录初始化、数据库初始化、全局监听注册再跑一遍。重复初始化这种问题前期不明显，后面会变成重复请求、重复回调、状态错乱。

6. 页面销毁后，异步回调还在改状态

启动之后经常伴随异步动作，比如查详情、拉配置、校验登录。页面销毁后回调还更新状态，就会出现偶现闪跳或者日志报错。

建议给异步任务加 taskId，或者在页面消失时取消。别让旧任务回来覆盖新页面。

稳定性优化：给启动链路加一个任务号

如果启动入口多，建议给每次 LaunchPayload 分配一个自增序号。后到的启动意图优先级更高，旧任务回来不能覆盖新状态。

这个设计不复杂，但很管用。

// common/launch/LaunchSession.ets
import { LaunchPayload } from './LaunchPayload'

export class LaunchSession {
  private currentSeq: number = 0
  private latest?: LaunchPayload

  next(payload: LaunchPayload): number {
    this.currentSeq += 1
    this.latest = payload
    return this.currentSeq
  }

  isLatest(seq: number): boolean {
    return seq === this.currentSeq
  }

  getLatest(): LaunchPayload | undefined {
    return this.latest
  }
}

页面或 RouterService 使用时：

const seq = launchSession.next(payload)

this.loadBizData(payload).then(() => {
  if (!launchSession.isLatest(seq)) {
    // 旧入口触发的异步结果，不允许覆盖新入口状态。
    return
  }

  // 更新页面或路由状态
})

用户从通知点进来，半秒后又从服务卡片点进来，两次入口都可能触发异步加载。没有序号保护，旧请求后回来就能把新页面状态盖掉。

很多"偶尔跳错详情"的问题，本质就是旧任务覆盖了新任务。这个问题不加日志很难看出来，加了任务号以后，一眼就能看出是谁回来晚了。

哪些场景更适合这么做

这套启动治理不是所有 demo 都需要。一个只有首页和设置页的小工具，没必要上来就搞一堆入口层封装。

但下面几类应用，我建议早点做：

• 内容类应用：从通知、搜索、外部链接进入文章或视频详情。
• 办公类应用：服务卡片进入审批、待办、日程详情。
• 电商和本地生活：活动链接、订单通知、桌面快捷入口都要落到不同业务页。
• 工具类应用：从分享、文件打开、Deep Link 进入不同编辑模式。
• 多 UIAbility 应用：主界面、独立编辑器、沉浸式展示页需要不同启动实例策略。

只要入口超过两个，就建议尽早把 Want 解析收敛掉。别等首页堆到几百行再重构，到那时候你已经分不清哪段逻辑是给哪个入口补的了。

结尾：入口治理写早一点，后面少还很多债

HarmonyOS 的 AbilityStage、Want、UIAbility，不只是应用模板里那几个默认文件。它们更像应用的入口骨架。

骨架稳了，页面和业务路由才不会到处补洞。

我的习惯是：AbilityStage 只做轻量进程级准备和分流；Want 进入应用后马上转成 LaunchPayload；UIAbility 统一处理冷启动和二次拉起；页面只消费归一后的业务参数。

看着多了几个类，但后面加入口、查问题、做灰度、做埋点，都会轻松很多。

别把启动参数散落在每个页面里。页面一多，谁都不愿意碰；入口一多，问题就开始像玄学。启动链路这种东西，越早工程化，越不容易在上线后给自己挖坑。