HarmonyOS元服务开发实战:AdventureWheel手机元服务配置、无签名HAP构建与API 23/20兼容完整指南

原创2026-11-12 21:14:062,303 阅读
文章标签:移动开发示例工程教程前端游戏开发

HarmonyOS元服务开发实战:AdventureWheel手机元服务配置、无签名HAP构建与API 23/20兼容完整指南

本文以 HarmonyOS 元服务「冒险大转盘(AdventureWheel)」为例子,带你完成一部手机元服务的完整配置:免安装(installationFree)属性怎么设、如何生成无签名 HAP 包,以及 API 23 / API 20 兼容版本如何声明。项目是一个朋友聚会用的真心话大冒险轮盘应用:随机抽取、转盘动画、本地存储与 JSON/TXT 文件迁移全在端侧完成,无需服务器。

冒险大转盘HarmonyOS元服务:首页设置、轮流转动转盘与本地任务库

项目概览:一个纯本地的聚会轮盘

打开 AdventureWheel,体验是「开局设置 → 清单确认 → 轮流转动 → 交接下一位」:

  • 选择「真心话 / 大冒险 / 混合局」,设置 2–20 个任务与最高挑战程度;
  • 点击「立即开始」先看本局清单,确认后转盘先快后慢,指针停在命中扇区;
  • 已处理的任务扇区变灰、标记「完成」,本局不再重复抽到;
  • 「任务库」内置 190 条任务(95 条真心话 + 95 条大冒险),自定义任务用 Preferences 保存在本机,并可导出 JSON 或分享 TXT 迁移到另一台设备。

技术上它只依赖手机侧原生能力:ArkUI 页面、Canvas 绘制 2.5D 转盘、Preferences 本地持久化、DocumentViewPicker 文件选择,目标是让新手能读懂「配置 → 构建 → 安装」这条链路。

关注点 说明
设备范围 仅手机(deviceTypes: ["phone"])
应用形态 免安装元服务(bundleType: "atomicService")
版本要求 目标 API 23(6.1.0),最低兼容 API 20(6.0.0)
签名 公开工程空签名配置,生成无签名 HAP

AdventureWheel手机元服务界面:轮流抽取转盘、完成扇区变灰、同局不重复

手机元服务配置:两个文件说清「免安装」

元服务和普通 App 的差异集中在两个配置文件里,AdventureWheel 的写法可以直接抄作业。

1. AppScope 层:声明 atomicService

AppScope/app.json5 决定应用的整体形态,关键就一行:

{
  "app": {
    "bundleName": "com.atomicservice.6917614463306867925",
    "versionName": "1.0.0",
    "bundleType": "atomicService"
  }
}
  • bundleType: "atomicService":标记为元服务,走免安装分发通道;
  • bundleName 使用 com.atomicservice. 前缀,符合元服务包名规范;
  • 独立开发自己的元服务时,换成自己申请的包名即可,其他结构不变。

2. entry 层:免安装 + 仅手机 + 桌面前台入口

entry/src/main/module.json5 里有三处对新手不明显的配置:

{
  "module": {
    "deviceTypes": ["phone"],          // 只声明手机
    "deliveryWithInstall": true,
    "installationFree": true,          // 元服务免安装的关键开关
    "abilities": [{
      "name": "EntryAbility",
      "skills": [{
        "entities": ["entity.system.home"],
        "actions": ["ohos.want.action.home"]
      }]
    }]
  }
}
  • installationFree: true:元服务可不落盘安装、即点即用,这是和普通 App 模块最大的区别;
  • deviceTypes 只写 phone:项目明确「只声明手机」,扩展平板、2in1 前需要先补专项验证;
  • skills 里的 ohos.want.action.home:让元服务出现在服务列表/桌面入口,点击后拉起 EntryAbility(源码见 EntryAbility.ets)。

三个页面注册在 pages 指向的 main_pages 配置中:首页设置、转盘页、任务库,页面代码位于 entry/src/main/ets/pages/。

AdventureWheel元服务实践卡片:进阶难度、约3小时完整实践、6项核心知识

无签名 HAP 构建:空签名配置是故意的

很多新手构建时看到这条提示会以为失败了:

No signingConfig found for product default

其实这是公开工程的预期状态。AdventureWheel 在 build-profile.json5 中把签名配置留空:

{
  "app": {
    "signingConfigs": [],
    "products": [{ "name": "default" }]
  }
}

构建成功后的产物是一个无签名 HAP,路径为 entry/build/default/outputs/default/entry-default-unsigned.hap(本次记录约 341 KB)。

场景 需要签名吗
生成 HAP、验证工程能否打包 不需要,无签名包即可
本地手机模拟器调试 按官方无签名调试方式,无需真机签名
真机调试安装 需要自己的调试签名(证书、私钥、描述文件)
云手机 按平台实际要求处理

安全红线:私钥、口令、签名 HAP 一律不提交进源码仓库。仓库自带检查脚本 tools/check-public-source.mjs 会扫描暂存区,发现签名引用(private-signing-reference 规则)直接报错,确保公开工程「干净」。

避坑:00303313 构建错误

如果你手动固定了 compileSdkVersion(例如写死 API 24),而工具链里装的是另一个 SDK,Hvigor 就会报 00303313。AdventureWheel 的做法是不固定编译 SDK,只用 IDE 配套版本:

  • 编译 SDK 随 DevEco Studio / HarmonyOS Command Line Tools 走;
  • 版本兼容声明仍然保留(见下节),二者互不干扰;
  • 修复后重新构建,并做设备回归,不要只看「BUILD SUCCESSFUL」就收工。

API 23/20 兼容设置:三个字段别搞混

版本声明全部集中在 build-profile.json5 的 products 里:

{
  "name": "default",
  "targetSdkVersion": "6.1.0(23)",     // 目标 API 23
  "compatibleSdkVersion": "6.0.0(20)", // 最低兼容 API 20
  "runtimeOS": "HarmonyOS"
}

三个容易混淆的概念,一张表理清:

配置 含义 AdventureWheel 取值
targetSdkVersion 按哪个 API 的行为规范编译 6.1.0(23)(API 23)
compatibleSdkVersion 允许安装到最低哪个 API 的设备 6.0.0(20)(API 20)
编译 SDK 实际使用的工具链版本 不固定,随 DevEco Studio 配套(记录中为 API 26)

验证方式也写进了发布流程:构建产物里的 pack.info 应出现 compatible: 20、target: 23,同时核对元服务属性 atomicService、installationFree: true、仅 phone。tools/check-public-source.mjs 同样会校验这两个版本号,一旦被人改掉会报 changed-target-or-minimum-api。

两个细节值得注意:

  • 编译版本 ≠ 最低可安装版本。用 API 26 SDK 编译,不代表不能在 API 20 设备上跑,但最低版本表现仍需真机/低版本模拟器实测;
  • 只声明了手机。如果以后要支持更多设备类型,deviceTypes 之外还要补大字体、多窗口等专项验证。

构建与验收清单

提交前按 docs/发布前核对.md 的顺序逐项确认即可:

测试脚本不能替代设备验收:ArkUI 渲染、Preferences 持久化、文件选择器和 TXT 实际接收,都必须在真机或模拟器上确认。

写在最后

AdventureWheel 的价值在于把一个 HarmonyOS 元服务必须掌握的三件事串成了一条可复现的链路:

  1. 元服务配置——atomicService + installationFree + skills 三处声明,见 AppScope/app.json5 与 entry/src/main/module.json5;
  2. 无签名构建——空 signingConfigs 生成 unsigned HAP,签名留给自己的调试环境;
  3. API 兼容——targetSdkVersion 6.1.0(23) / compatibleSdkVersion 6.0.0(20),编译 SDK 交给工具链。

想继续深入,推荐阅读 docs/设计说明.md(两层随机规则、转盘动画与本地架构)、docs/任务文件格式.md(导入导出的字段契约)和 data/内置任务-v1.0.json(190 条教学任务数据),配合 README.md 里的云端 / 本地两条体验路径,15–30 分钟就能把「确认清单 → 转动 → 交接 → 任务库」完整跑一遍。

登录后查看全文
HarmonyOS-AtomSer-AdventureWheel