企业官网建设流程全解析

干鸿蒙开发这段时间，我越来越觉得UIAbility是整个应用模型里最值得先啃透的一块。简单说，UIAbility就是你在系统里能看到、能点开、能反复启动的那个“入口能力”——类似安卓里的Activity，但鸿蒙在实例管理上又完全不一样。标题里提到的“启动模式”不是玄学，不是配置模板，而是直接决定你应用占几个任务、复用哪套逻辑、数据从哪来。这篇文章不绕弯子，把这四种启动模式从原理到配置再到踩坑一次说清楚。

先说明白一个背景：当前官方文档里启动模式分类看多，但核心就四类——多实例、单实例、单任务、指定实例。其中前三类在module.json5里通过launchType字段配置，最后一类没有这个字段，走的是startAbilityBySpecifiedAbility专用流程。很多初学者看到“singleton”和“singleTask”就以为是一个东西，或者以为“多实例”就是“每次都新建”，实际上差别非常大。下面逐个拆。

1. 先从UIAbility说起：为什么启动模式值得单独开一节

1.1 UIAbility在应用模型里的位置

在HarmonyOS的Stage模型里，UIAbility是承载UI界面的系统级组件，一个应用可以有一个或者多个UIAbility，每个UIAbility通常对应一个可以独立启动、独立进入最近任务列表的“能力入口”。比如你的应用有主页面、有视频播放页、有设置页，你可以全放一个UIAbility里用Navigation管理，也可以拆成多个UIAbility让系统直接拉起不同的任务。

官方文档里的定义比较抽象，我做安卓时常拿Activity类比，但这类比其实有坑。Activity的launchMode和UIAbility的launchType表面上都是“启动策略”，实际底层一个是ActivityRecord的栈管理，一个是Mission（任务快照/任务卡片）的创建与复用。如果你照搬安卓那套思维来理解鸿蒙的启动模式，后面看生命周期会懵。

在Stage模型里，每次真正“拉起”UIAbility，系统都会创建一个Mission，这个Mission会出现在最近任务列表里。启动模式决定了这个Mission怎么分配：是每次都创建一个新Mission，还是复用已有Mission，还是给同一种UIAbility创建多个不同身份但有上下限的Mission。

1.2 为什么开发者必须理解启动模式

最常见的翻车现场：音乐应用里，用户从桌面图标进入是A实例，从通知栏点播放又拉起一个实例，结果最近任务里出现两个一样的音乐播放器，切来切去状态完全不同步。这不是代码逻辑问题，是启动模式没设计好。

反过来，有些应用希望每次打开都是全新状态，比如浏览器标签、多窗口文档编辑器，你偏偏配成单实例，用户点一次新建就跳到已有页面，业务根本跑不通。

所以启动模式不是“优雅设计”，是刚需。理解了它，你才知道：

• 什么时候用哪个模式
• 实例复用后哪些生命周期回调会触发
• 如何通过want参数把“这次要干什么”传给新实例或旧实例
• 为什么有时候onCreate没走，数据却应该在onNewWant里更新

2. 四种启动模式逐个拆解：配置方式与适用场景

2.1 multiton（多实例模式）：默认选择，每次启动都是新副本

多实例模式是系统的默认行为，在module.json5里不写launchType或者显式写"multiton"都行。每次startAbility，系统都会创建一个全新的UIAbility实例，分配新的Mission，走完整的onCreate流程。

用生活场景类比：相当于食堂窗口每次来客人就新开一份餐，不管前一份吃完没。这样做的好处是隔离干净，每个实例的页面栈、临时数据、内存状态各自独立，互不干扰。坏处也很明显——内存压力大，任务窗口可能会堆积出很多相同的任务卡片。

实际开发里什么时候选它？核心就四个字：状态隔离。比如笔记类应用，用户新建多个文档窗口，每个窗口都应该有独立的内容。又比如多账号同时在线，A账号和B账号的会话列表必须分开，如果用单实例，要么手动切来切去，要么就得在同一个UIAbility里做复杂的状态路由，容易乱。

配置方式在module.json5的abilities数组里直接设置：

{ "module": { "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ets", "launchType": "multiton", "description": "$string:EntryAbility_desc" } ] } }

这里有个细节：srcEntry只是入口文件路径，实际类名由name字段决定。很多人把name和文件路径搞混，导致改launchType后编译报错或者配置不起作用，新手容易在这块卡住。

2.2 singleton（单实例模式）：全局唯一的入口

singleton翻译过来是单实例，意思很直接：整个系统范围内，这种UIAbility最多只存在一个实例。第二次、第三次启动它时，系统不会创建新实例，而是把之前的实例从后台切到前台，然后触发onNewWant回调，把这次启动的Want参数传进去。

这相当于你家里只有一个客厅，不管谁来找你，你都把他带到同一个客厅里坐，然后告诉他“这次来的目的是什么”。

典型场景太多了：

• 音乐播放器：从桌面、通知栏、耳机手势各种入口启动，都应该回到同一个播放页，保持当前播放状态
• 支付安全页面：避免多个支付入口叠加出多个安全校验实例
• 首页 / 主入口：不让用户在最近任务里刷出一堆相同的首页卡片

配置方式同样是改launchType：

{ "module": { "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ets", "launchType": "singleton", "description": "$string:EntryAbility_desc" } ] } }

需要注意：单实例模式下，实例只有一个，但Mission也一样只有一个。也就是说用户把应用滑掉销毁后，再启动才会走完整的onCreate创建新实例；如果只是退到后台，再点图标启动，系统会优先复用那个还活着的实例。

我在项目里遇到过一种情况：用户从桌面进应用，然后又点另一个业务入口，期望是“重新开始一个完整的流程”，结果因为singleton直接把旧页面栈带回来了。这时候不能让实例“自动失忆”，必须自己在onNewWant里做栈清理和页面重置。

2.3 singleTask（单任务模式）：栈内复用的业务逻辑

singleTask是三种launchType里最容易被误解的。字面意思是“单任务”，但它的核心行为是：如果这个UIAbility的实例以及它所在的任务栈中已经存在对应任务，那么系统复用这个任务里的UIAbility实例，并且把该任务栈中这个实例之上的所有页面全部销毁，让这个实例回到栈顶。

画个图感受一下：

• 任务栈里现在有：首页(EntryAbility) → 详情页(DetailAbility)
• 详情页里调起启动一个singleTask的MainAbility
• MainAbility之前不在这个栈里，系统会新建MainAbility，放进栈里
• 下次从另一个入口启动MainAbility时，如果系统发现栈里已经有MainAbility，直接把MainAbility上面的页面清掉，让MainAbility成为栈顶

这个模式解决的是“一个业务流程里某个能力应当唯一，但业务页面可以堆叠”的问题。典型场景是收银台、支付结果页、登录页——你从多个页面发起支付，最终都回到同一个支付结果页，而不是每次买完东西都堆一个支付页面。

配置上跟前面一样：

{ "module": { "abilities": [ { "name": "PayAbility", "srcEntry": "./ets/payability/PayAbility.ets", "launchType": "singleTask", "description": "$string:PayAbility_desc" } ] } }

很多人会问：singleton和singleTask都是“只复用”，区别到底在哪？我总结为两点：

• 作用范围：singleton在整个系统维度上保证同类UIAbility只有一个实例；singleTask是在任务栈维度上尽量复用，并且允许不同任务栈里存在多个实例
• 页面栈策略：singleton复用时不关心栈顶是什么，直接拉旧实例到前台；singleTask复用时会清掉目标实例之上的所有页面，强制让目标实例成为唯一栈顶

实际开发中，如果你只需要“全局唯一入口”，选singleton；如果需要“业务流程里某个能力页唯一，同时自动清理其上层的脏页面”，选singleTask。

2.4 specified（指定实例模式）：多身份复用的高阶玩法

前面三种模式都是系统按固定规则分配实例。specified不一样，它把一部分权力交给开发者：你通过Want参数里的某个自定义key来指定“我要启动或复用的是哪一个实例”。

打个比方，这套机制像一个带房间号的酒店前台。你入住时告诉前台你是“用户A”，前台在酒店里找有没有属于用户A的房间；有，就带你去，没有，就开一间并挂上用户A的牌子。这里的“用户A”就相当于instanceKey。

specified模式没有launchType字段，它的使用场景很具体：同一个UIAbility，因为承载的主体不同（不同账号、不同文档、不同聊天对象），需要同一个Ability类，但多个互不干扰的实例。典型例子是聊天窗口：同时打开跟张三、李四的对话窗口，它们渲染逻辑同一个文件，如果只用一个实例，来回切换很麻烦；如果每次新建多实例，每个实例都是空白的，不知道是谁的会话。正确的做法是用一个“实例标识”去区分，实例存在就复用，不存在就创建。

代码分成两步。

第一步，启动方调用startAbilityBySpecifiedAbility，并且在want.parameters里放入instanceKey：

import { Want, common } from '@kit.AbilityKit'; let context = getContext(this) as common.UIAbilityContext; let want: Want = { bundleName: 'com.example.chatapp', abilityName: 'ChatAbility', moduleName: 'entry', parameters: { instanceKey: 'chat_with_zhangsan', targetName: 'zhangsan' } }; context.startAbilityBySpecifiedAbility(want, { onRequest: (want, launchParam) => { return { key: want.parameters?.instanceKey as string, abilityName: 'ChatAbility', moduleName: 'entry', parameters: want.parameters }; }, });

onRequest回调里返回的key就是实例标识。系统拿这个key和当前已有的specified实例对比，如果匹配，就走复用流程，触发onNewWant；如果不匹配，就创建新实例。

第二步，被启动的UIAbility里需要处理两种启动路径：新实例的onCreate，和复用实例的onNewWant。

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; import { window } from '@kit.ArkUI'; export default class ChatAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { const instanceKey = want?.parameters?.instanceKey as string; // 根据instanceKey初始化数据源 } onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { const instanceKey = want?.parameters?.instanceKey as string; // 复用实例时，刷新页面数据，不能重复做onCreate的初始化工作 } onWindowStageCreate(windowStage: window.WindowStage): void { // 正常加载页面 } }

specified模式是四种模式里最灵活的，但灵活带来的代价是你要自己保证key的规范。比如聊天场景里，如果用“目标用户ID”做key，那切换账号后，同样的目标用户ID可能被两个账号共用，实例就会被错误复用，导致数据串号。建议key里带上账号维度，例如accountId + '_' + targetId。

3. 实操演示：从配置文件到代码启动的一次完整闭环

3.1 module.json5里的launchType怎么配

所有UIAbility的启动模式都需要在工程的module.json5里静态声明，代码里是没有“动态修改启动模式”这个操作的。工程默认创建时会生成一个EntryAbility，你可以在src/main/module.json5的abilities数组里找到它：

{ "module": { "name": "entry", "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ets", "description": "$string:EntryAbility_desc", "icon": "$media:layered_image", "label": "$string:EntryAbility_label", "startWindowIcon": "$media:startIcon", "startWindowBackground": "$color:start_window_background", "exported": true, "launchType": "singleton", "skills": [ { "entities": ["entity.system.home"], "actions": ["action.system.home"] } ] } ] }

我强烈建议把launchType放在显眼的位置，方便排查。很多团队协作项目里，别人偷偷改了你的启动模式，你还在调试台上疯狂看日志，结果发现是配置文件变了，这种浪费时间的排查最冤。

另外注意：launchType的取值是小写字符串，不能像枚举那样写成LaunchType.SINGLETON，配置文件里写错不会直接报红，但运行时不会被识别，系统会按默认的multiton处理，问题特别隐蔽。

3.2 代码启动UIAbility的两种姿势

从代码层面看，启动UIAbility的核心API是startAbility。在任意页面组件里，你可以通过getContext(this)拿到UIAbilityContext，然后调用startAbility：

import { Want, common } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct Index { startEntryAbility() { let context = getContext(this) as common.UIAbilityContext; let want: Want = { bundleName: 'com.example.myapp', abilityName: 'EntryAbility', moduleName: 'entry', parameters: { from: 'mainPage', needRefresh: true } }; context.startAbility(want).then(() => { console.info('startAbility success'); }).catch((err: BusinessError) => { console.error(`startAbility failed, code: ${err.code}, message: ${err.message}`); }); } }

如果你启动的是应用自己的Ability，bundleName可以省略或者填自己的包名；跨应用启动时bundleName和abilityName都要写全。parameters是数据传输的关键通道，后面在目标UIAbility里通过want.parameters取出来，可以实现“入口参数导航”。

第二种姿势是前面提到的specified模式专用API，startAbilityBySpecifiedAbility。它比startAbility多一个回调参数，用来返回实例key：

context.startAbilityBySpecifiedAbility(want, { onRequest: (want, launchParam) => { return { key: want.parameters?.instanceKey as string, abilityName: want.abilityName ?? '', moduleName: want.moduleName, parameters: want.parameters }; }, }).then(() => { console.info('startAbilityBySpecifiedAbility success'); }).catch((err: BusinessError) => { console.error(`failed, code: ${err.code}, message: ${err.message}`); });

onRequest的入参里其实也能拿到Want，这就是为什么你可以在回调里把外层的instanceKey原样返回。如果我在这个回调里硬编码一个固定key，就等于把specified模式退化成了singleton——所有启动请求都映射到同一个实例，想开多个窗口都开不出来。

3.3 参数传递与实例标识的配合使用

想用好启动模式，必须把want参数玩熟。want是鸿蒙组件间通信的核心载体，本质上是一个可序列化的对象，包括deviceId、bundleName、abilityName、moduleName、parameters等字段。

启动方往parameters塞数据，接收方在onCreate或者onNewWant里取：

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { if (want?.parameters) { const from = want.parameters.from as string; const needRefresh = want.parameters.needRefresh as boolean; // 根据入口来源做不同的页面初始化 } }

一个特别容易出错的点：跨实例传递对象时，parameters里不能放无法序列化的对象。官方支持的类型是JsonValue相关类型，比如string、number、boolean、数组和能转JSON的对象。如果硬塞一个类的实例进去，轻则字段丢失，重则直接抛异常。

对于specified模式，instanceKey的传递也走parameters。有一个非常隐蔽的坑：如果启动方只传了目标对象ID，没传账号维度，那么在多用户场景下，实例就会串号。我踩过一次，查了一天，最后发现是key设计得太短，只用了chatId，没有拼上userId。用层级Key是个好习惯：

parameters: { instanceKey: `account_${accountId}_chat_${chatId}` }

4. 启动模式相关的生命周期细节与状态恢复

4.1 onCreate、onNewWant与onDestroy的触发关系

理解了启动模式，必须同步理解生命周期回调的变化。四种模式下，onCreate的触发频率完全不同：

• multiton：每次启动都会走onCreate，onDestroy也可能频繁触发
• singleton：第一次创建时走onCreate，之后复用走onNewWant，完全不会走onCreate
• singleTask：复用时会先触发onNewWant，并且把实例上方页面销毁
• specified：新实例走onCreate，已有实例走onNewWant

放一个表更直观：

这个表帮我避免了很多“数据没刷新”的bug。理解之后你就明白，单实例下onNewWant里写的数据刷新逻辑，比onCreate里的初始化更重要，因为大部分启动事件都会走onNewWant。

生命周期完整顺序，以冷启动为例：

onCreate → onWindowStageCreate → onForeground → 页面可见

从后台切回前台（进程还活着）：

onForeground

注意：没有onNewWant，因为系统只是把已有实例切到前台，不是“启动”一次新意图。只有另一个UIAbility通过startAbility想复用这个实例时，才会触发onNewWant。

4.2 冷启动与热启动：复用实例时的状态管理

launchParam里有LaunchReason，可以明确区分这次启动是冷启动还是热启动。代码里可以这样取：

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { const reason = launchParam.launchReason; // AbilityConstant.LaunchReason.COLD / HOT / RECENT if (reason === AbilityConstant.LaunchReason.COLD) { // 冷启动：全新创建，需要完整初始化 } else if (reason === AbilityConstant.LaunchReason.HOT) { // 热启动：实例已存在，可能带了新want参数 } } }

这个判断在单实例场景下尤其关键。比如音乐应用，冷启动时你需要从零加载歌单，热启动时只需要更新当前播放歌曲。如果每次都在onCreate里重做一遍，除了慢，还可能把用户正在听的音频状态打断。

另外，实例复用时，还要考虑页面栈的恢复问题。singleton模式里，用户上次退出时停在了详情页，这次从图标进入，系统会把旧任务栈整体带回来，页面还停在详情页。如果你希望“从桌面图标进入时直接回到首页”，需要在onNewWant里做一次页面栈重置，比如通过router.clear()或者Navigation的clearStack方法。

不要以为首页Ability配了singleton就天然“回到第一页”，它只保证实例唯一，不保证页面栈干净。

5. 踩坑实录：我在这块儿遇到过的典型问题

5.1 启动模式不生效，反复创建新实例

有段时间我在模拟器上调试，明明module.json5里写了"launchType": "singleton"，但每次startAbility都会创建新实例，最近任务里一排相同的任务卡片。

排查后发现两个原因：

• 改了module.json5之后没有重新编译，模拟器跑的还是旧包。鸿蒙的配置文件变更不会热更新，必须重新构建。
• module.json5里拼写检查漏了，写成了"singleton"是没问题的，但有些人会写成"Singleton"或者"single"这种不存在的枚举值，识别不了就默认回退到multiton。

所以第一排查建议：直接看构建产物或者用hdc查当前安装包的配置，别光盯着代码。

5.2 单实例下onNewWant带过来的参数没处理

这是个非常典型的逻辑漏洞。有一次做购物应用，登录页配成singleton，用户从A商品页拉起登录，登录成功后再从B商品页拉起登录，结果发现第二次拉起的商品ID没被处理，页面显示的永远是A商品的后续内容。

原因是实例复用后只触发了onNewWant，但页面没有监听这次Want传递的新参数。修复方向有两个：

• 在onNewWant里解析want.parameters，然后通过全局状态或事件总线把数据传给页面组件
• 使用singleton时，尽量把“这次启动要干什么”变成全局路由事件，不要依赖界面的原生 onCreate 参数

5.3 specified模式的实例键冲突

specified模式最大的坑是key命名。两个不同的业务模块如果都用"instanceKey"作为参数名，系统根本不知道你是哪个模块，只看key的值。假如模块A用"123"代表商品详情，模块B也用"123"代表用户详情，那就会出现串页面。

解决办法是给key加语义前缀，比如product_123、user_123。在返回onRequest的key时，一定要和启动方传入的key保持一致，最好直接透传，不要自己再加工一遍。有个同事曾经在onRequest里做了字符串格式化，前后两次key不一致，实例就一直创建不成功，绕了不少弯路。

另外，指定实例也需要处理实例上限。如果用户一直创建新聊天窗口，specified实例会越来越多，内存压力不可忽视。可以在onDestroy或业务里做数量管理，超出允许上限后主动销毁最老的实例。

5.4 从旧模型转过来时的认知迁移陷阱

如果你之前接触过FA模型或者安卓Activity，转Stage模型后会有一段特别拧巴的时间。Activity的singleTask和鸿蒙singleTask行为类似，但底层机制完全不同，Activity的单实例是进程内的任务栈管理，鸿蒙的Mission管理还牵扯系统级任务中心。对比维度一多，就很容易照搬旧逻辑。

我的建议是不要背结论，直接把启动模式的设计目的想清楚：

• 状态要隔离，用多实例
• 全局唯一，用单实例
• 业务流程内唯一且清栈，用单任务
• 同一套页面要开多个有身份的实例，用指定实例

想清楚这四句话，配置和排查基本不会跑偏。

6. 最后再分享两个小技巧

如果你刚接触UIAbility，我建议在你的工程里单独写一个启动模式测试页，把四种模式各配一个Ability，用一个列表页分别去启动它们。启动之后立刻去最近任务列表看，任务卡片数量变化一目了然。这种动手验证比照着文档理解快很多，我当初就是这么把概念彻底搞清楚的。

还有一个技巧，在onNewWant里记得打印want和launchParam的完整内容。实例复用时的bug，绝大多数都是因为参数没对上传、没对上取。日志是最直接的下手点。

启动模式理解了，UIAbility的地基就算打牢了。接下来不管你做页面导航、多窗口还是应用间跳转，都顺手得多。希望这篇文章能帮你少走我走过的弯路。