Skip to content

元服务开发与上架:免安装背后的工程账 ​

这个类目只讲一件事:免安装不是免费的,你只是把成本换了个地方付。

学习目标:读完能判断什么 ​

读完这一篇,希望你能做到四件事:

  • 能判断一个业务动作该做成元服务、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 形态单独设计。

json
{
  "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()。但它有配额,后台频繁刷新会被系统限流。所以刷新策略要按「信息变化频率」设计,不是按「我想让它看起来是实时的」。

ts
// 主动刷新:受配额限制,只在数据真的变化时调用
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 是嵌套的:

ts
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,用户感知变好了,但你的二级页首次进入变慢了。这个交换值得吗?判断依据应该是什么?