HarmonyOS元服务开发实战:AdventureWheel手机元服务配置、无签名HAP构建与API 23/20兼容完整指南
HarmonyOS元服务开发实战:AdventureWheel手机元服务配置、无签名HAP构建与API 23/20兼容完整指南
本文以 HarmonyOS 元服务「冒险大转盘(AdventureWheel)」为例子,带你完成一部手机元服务的完整配置:免安装(installationFree)属性怎么设、如何生成无签名 HAP 包,以及 API 23 / API 20 兼容版本如何声明。项目是一个朋友聚会用的真心话大冒险轮盘应用:随机抽取、转盘动画、本地存储与 JSON/TXT 文件迁移全在端侧完成,无需服务器。
项目概览:一个纯本地的聚会轮盘
打开 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 |
手机元服务配置:两个文件说清「免安装」
元服务和普通 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/。
无签名 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 的顺序逐项确认即可:
- [ ] 构建成功,
entry-default-unsigned.hap存在,且是本次构建产物而非旧文件; - [ ]
pack.info中compatible: 20、target: 23,包内atomicService、installationFree: true、phone; - ] 17 项纯逻辑规则测试通过(覆盖随机抽样、同局去重、190 条任务 ID 唯一性等,运行 [tools/run-logic-tests.mjs);
- [ ] 公开范围扫描
PASS:无签名材料、无本机路径泄漏; - [ ] 设备上实际「清单确认 → 转动 → 交接 → 完成」跑通一轮,安装成功不等于运行成功。
测试脚本不能替代设备验收:ArkUI 渲染、Preferences 持久化、文件选择器和 TXT 实际接收,都必须在真机或模拟器上确认。
写在最后
AdventureWheel 的价值在于把一个 HarmonyOS 元服务必须掌握的三件事串成了一条可复现的链路:
- 元服务配置——
atomicService+installationFree+ skills 三处声明,见 AppScope/app.json5 与 entry/src/main/module.json5; - 无签名构建——空
signingConfigs生成 unsigned HAP,签名留给自己的调试环境; - 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 分钟就能把「确认清单 → 转动 → 交接 → 任务库」完整跑一遍。


