元服务开发与上架:免安装背后的工程账
这个类目只讲一件事:免安装不是免费的,你只是把成本换了个地方付。
学习目标:读完能判断什么
读完这一篇,希望你能做到四件事:
- 能判断一个业务动作该做成元服务、App,还是「元服务做入口 + App 做深度」。
- 能说清免安装省掉的安装时间,究竟被转移到了哪一段用户等待里。
- 能独立写出一张有多个尺寸、刷新策略合理、点击能带回参数的卡片。
- 会判断上架前哪四项会被审核抽样打回,而不是等提交后看驳回理由。
不要求你背 API。要求你能在立项会上给出结论和理由。
知识位置:它在这个体系的哪一格
用户点一张桌面卡片,两秒内要看到结果。这个两秒,比技术栈更能决定元服务长什么样。
技术栈上它和 App 几乎没差别:ArkTS、ArkUI、Stage 模型、同一套 hvigor。团队切过去几乎没有学习成本。
差别在分发。用户不安装、不看详情页、不看完开屏动画,点一下就要出结果。
技术栈相同、分发模型不同——这一句是全篇的支点。它推出三个边界:能写什么由 API 集合决定,能写多厚由首包决定,能不能上线由审核规范决定。
先建立一个判断习惯
以后看到「能不能做成元服务」这个问题,先别答。改成问:「这个业务有没有一个高频、单点、能被卡片承载的动作?」
差集:少掉的到底是什么
把元服务理解成「精简版 App」是第一个误解。它不是精简版,是子集。
| 维度 | 元服务 | App |
|---|---|---|
| 获取方式 | 免安装,点击即用,服务随华为账号同步 | 下载安装,占桌面图标 |
| 可用 API | 仅「元服务 API 集」,API 参考里可勾选筛选 | 全量开放 API |
| 后台能力 | 弱,长时任务、常驻后台基本不可用 | 支持长时任务、后台播放 |
| 入口 | 服务中心、应用市场、小艺、全局搜索、扫码、桌面卡片 | 桌面图标、推送、桌面卡片 |
| 退出 | 即用即走,退出无弹窗 | 可驻留、可引导 |
| 审核 | 额外的元服务规范 | 应用审核规范 |
反例很具体:把 App 首页的 20 个页面砍成 5 个搬过来,那不是元服务化,那是一个残缺的 App。它既没有 App 的深度,也没有元服务的爽快。
第二个推论更实际。元服务真正的价值不在「少装一个 App」,而在入口的组合——卡片常驻桌面、小艺语音直达、扫码直达、搜索结果直达。这些入口在应用形态下要么拿不到,要么成本高得多。
动手压首包:只留入口和卡片
免安装把「下载安装」这段时间挪到了用户点击之后。
用户感知到的不是进度条,是「点了没反应」。所以包结构设计只有一个目标:首包尽量小,其余全部按需。
HarmonyOS 支持分包加载(HSP),运行时按需下载并挂载。工程手法就四条:
- 主包只放入口页、卡片和启动必需资源。卡片资源必须在首包里,不能等分包。
- 大图、字体、音视频一律外置。图片走 CDN 按屏幕密度取;端侧模型这类几十 MB 的资产,元服务形态基本不该带。
- 非首屏页面用动态
import()拆到分包。 - 初始化分两段:首帧必需的(主题、路由、账号态)同步做;埋点、AB、配置拉取放到首帧之后。
这张图的重点是成本转移:免安装省掉的等待没有消失,它被压进了「点击到首帧」这一段。而这一段的时间,几乎完全由首包体积决定。
预期输出可以量化。一个把 App 首页原样搬过来的元服务,首包 8MB 起步,点击后白屏约两秒,用户基本直接退出。压到「入口页 + 卡片」之后,这段等待能回到用户可以接受的范围。
怎么验证压对了没有?在目标真机上打开飞行模式,从桌面卡片点进去。首包里的东西必须能渲染出来;报错、白屏、只有骨架屏没有内容——三种都说明有资源被漏在分包里了。这个测试比看构建产物里的包体数字更直接,因为它模拟的正是用户第一次点击时的真实状态。
截至 2026 年 11 月,元服务文档在 HarmonyOS 开发者文档的「元服务」分区持续更新,HarmonyOS 6.1.x(API 23、24)是当前主力版本。包体阈值和审核细则以 AGC 上传校验、以及当年发布的《元服务审核指南》为准,本文讲的是那些不随版本变化的结构性约束。入口在 HarmonyOS 开发者文档中心。
卡片:第二种 UI 形态,不是页面裁剪出来的
卡片运行在独立的卡片进程中,能用的组件与 API 是 ArkTS 的子集。依赖窗口、焦点、页面路由、完整动效链路的能力,基本都用不了。
这里容易卡住的地方是:把页面组件直接复用到卡片上,编译能过,渲染空白。没有报错,没有堆栈,只有一个空白卡片。
正确姿势是把卡片当成第二种 UI 形态单独设计。
{
"forms": [
{
"name": "todo_widget",
"src": "./ets/widget/pages/TodoWidget.ets",
"uiSyntax": "arkts",
"updateEnabled": true,
"updateDuration": 2,
"defaultDimension": "2*2",
"supportDimensions": ["2*2", "2*4", "4*4"]
}
]
}这里有个只有实际配过才知道的细节
updateDuration 的单位是 30 分钟。写 2 不是每 2 分钟刷一次,是 2 个半小时格,也就是每小时刷一次。 第一次调的时候我盯着卡片等了十分钟,以为是配置没生效。想按具体时刻刷,用 scheduledUpdateTime,比如早八点的日程卡。
刷新还有第三条路:主动调 formProvider.updateForm()。但它有配额,后台频繁刷新会被系统限流。所以刷新策略要按「信息变化频率」设计,不是按「我想让它看起来是实时的」。
// 主动刷新:受配额限制,只在数据真的变化时调用
async function refreshWidget(formId: string, count: number): Promise<void> {
const data = formBindingData.createFormBindingData({ title: '今日待办', count });
try {
await formProvider.updateForm(formId, data);
} catch (e) {
const err = e as BusinessError;
// 常见失败:formId 已失效(卡片被移除)、刷新过频被限流
console.error(`updateForm failed: ${err.code} ${err.message}`);
}
}跳转这条链路上有个参数层级容易写错。卡片里 FormLink 的 params 是嵌套的:
FormLink({
action: 'router',
abilityName: 'EntryAbility',
params: { params: 'pages/TodoList?from=widget' }
})取的时候是 want.parameters.params,多一层。写成 want.parameters 直接取,拿到的是 [object Object]。
而且冷启动走 onCreate、应用已在后台走 onNewWant,两处都得接。只接前者,表现就是「点了没反应」。
还有一条必须写进设计:formId 的生命周期比应用进程短。卡片被用户移除后旧 formId 立即失效,所有刷新都会失败。刷新逻辑必须能吞掉这个异常,不能把它当可靠通道。
上架:真正会卡住你的四处
名称。不能与已有元服务重名,不能用「天气」「外卖」这类广义归纳词,不能有诱导性表述。名称在 AGC 创建时固定,改名的成本远高于上线前多想半天。
卡片合规。声明的每个尺寸都要有对应布局。只声明不实现,审核抽样时判「卡片显示异常」。这条最容易被跳过,因为本地只测了常用的那个尺寸。
即用即走。不能有开屏广告、不能强制登录、不能强制跳转下载 App、退出不能有挽留弹窗。这几条是产品定义,不是建议。
兼容性与资质。声明支持平板的要做平板兼容性测试;支付、医疗、金融等类目要相应资质;隐私政策与实际采集的权限必须逐条对应。申请了定位却不在隐私政策里说明,是最常见的驳回原因之一。
这里给一个明确判断:不建议把元服务做成 App 的引流外壳。强制跳转下载、退出挽留、首屏登录框,这三样凑在一起,既违反即用即走的审核要求,也把元服务唯一的优势——点一下就有结果——主动放弃了。引流该在结果页之后做,不该在结果之前拦。
容易想反的三件事
很多人以为元服务和 App 是二选一,实际上是三种组合并存。最常见的是元服务做入口、App 做深度;其次是共用后端与业务代码(网络层、数据模型、埋点封装成 HAR,两边各自引用);第三是共用账号但不共用登录页,用 Account Kit 做静默授权。
很多人以为抽成 HAR 就一定能两边复用,实际上 HAR 里不能出现只有 App 才能用的 API。轻则元服务侧编译不过,重则编译通过、跑到那个分支才崩,因为元服务运行时根本不提供那套接口。
很多人以为元服务的后台能力和 App 一样,实际上长时任务、常驻后台基本不可用。导航、录音这类需要后台驻留的业务,只能做 App。
名词对照:六个词
| 术语 | 英文 | 一句话解释 |
|---|---|---|
| 元服务 | Atomic Service | 免安装、即用即走的应用形态,API 是 App 的子集 |
| 服务卡片 | Form / Widget | 常驻桌面的展示面,跑在独立卡片进程里 |
| 分包 | HSP | 运行时按需下载并挂载的包,用来压首包 |
| 首帧 | First Frame | 从用户点击到界面可见的那一段,元服务的关键指标 |
| 卡片配额 | Form Update Quota | 主动刷新卡片被系统允许的频率上限 |
| 垂域意图 | Domain Intent | 交给系统分发入口的功能声明 |
留三道题
第一道:如果你的业务有「查订单」和「下单」两个动作,分别该放哪一侧?想清楚转化路径和审核红线再答。
第二道:一张卡片声明了 2*2、2*4、4*4 三个尺寸。用户把桌面拉成 4×4,你的列布局会发生什么?如果没写 height('100%') 呢?
第三道:首包从 8MB 压到 1MB,用户感知变好了,但你的二级页首次进入变慢了。这个交换值得吗?判断依据应该是什么?