在HarmonyOS 6设备预置应用（Pre-installed App，未上架华为应用市场）的开发中，最容易被遗漏的一步是：还没在AppGallery Connect（AGC）创建应用就拿APPID往签名文件里填。结果要么是签名校验失败无法安装，要么是调用定时任务、推送、账户等依赖APPID的系统能力时直接返回错误码。

官方文档明确答复——无论应用是否上架应用市场，都必须在AGC中创建HarmonyOS应用以获取合法唯一的APPID。本文将完整说明原因、操作步骤及预置应用特有注意事项。

---

一、现象：预置包装不上或系统能力调不通

1. 典型踩坑场景

你做了什么	预期	实际结果
用自定义调试证书直接打HAP，bundleName随便写	预置进系统镜像可安装	❌ 安装失败或bm install报错"app identifier invalid"
在module.json5填了bundleName但未建AGC应用	调用reminderAgent.publishReminder()正常	❌ 返回错误码，服务端查不到该APPID
AGC创建了项目但没建应用	获取APPID配置签名	❌ "该项目中无HarmonyOS应用，无法生成APPID"

2. 根因揭秘：APPID是系统能力的"身份证"

HarmonyOS中 APPID（Application ID）​ 由AGC统一分配，格式通常为：

{DeveloperID}_{ProjectID}_{BundleName简写}   // 示例: 10123045_1234567890_com_example_myapp

它会被写入最终HAP包头信息，并用于：

• 包名校验与预置白名单匹配（系统判断该包是否允许预置）

• 系统服务能力鉴权（Reminder、Push、Account、Distributed Scheduler等需校验APPID合法性）

• 签名证书绑定（调试/发布证书关联AGC项目）

失败本质：未经过AGC创建 → 无合法APPID → 签名虽过但运行时鉴权失败，或预置镜像中preinstall目录扫描时被安全策略拦截。

---

二、解决方案：预置应用建AGC应用全流程SOP

Step 1：AGC创建项目（若已有可跳过）

1. 登录 AppGallery Connect

2. 我的项目 → 新建项目​ → 填写项目名称、选择 HarmonyOS​ 平台

3. 记录 项目ID（Project ID）

Step 2：在项目下创建HarmonyOS应用（关键！）

1. 进入刚创建的项目 → 应用/元服务 → 新建应用

2. 填写：

   • 应用名称：如预置设置助手

   • 包名（Bundle Name）：必须与你要打的HAP中bundleName完全一致（如com.example.preinstalledapp）

   • 设备类型：勾选目标预置设备（手机/平板/穿戴等）

3. 点击创建 → AGC生成并显示 APPID

4. 记录该APPID（后续填入签名Profile和文档交付ODM厂商时用）

⚠️ Bundle Name一旦创建不可修改，预置镜像中的白名单需与此包名严格匹配。

Step 3：配置签名证书（调试/预置）

• 调试阶段：DevEco Studio → Project Structure → Signing Configs​ → 勾选Automatically generate signing，AGC会自动关联刚才创建的应用，下载调试证书

• 预置正式包：在AGC "证书、APP ID和Profile → 发布证书"​ 申请发布证书，创建Profile时绑定该应用，用此Profile打HAP

签名产物中会自动嵌入AGC下发的APPID，无需手动粘贴。

Step 4：验证APPID已写入包内

# 解压HAP查看manifest（示意）
aapt dump badging entry-default-signed.hap | grep "package"
# 或用DevEco的Build Analyzer查看 bundleName与appId一致

---

三、预置应用特别注意事项

项目	说明
bundleName一致性​	AGC应用包名 = HAP中bundleName= 预置白名单中登记包名
APPID不手工构造​	永远用AGC生成的，手工拼ID可能导致格式不匹配被系统拒绝
权限预授权​	预置应用如需SYSTEM_CORE级权限，需配合设备allow-list.xml向ODM申请，不靠AGC自动赋予
不上架声明​	AGC应用可一直保持"未上架"状态，不影响预置包使用系统能力
多设备同包名​	若手机/穿戴共用一个bundleName，AGC应用勾选多设备类型即可

---

四、避坑速查

问题	排查点
定时提醒/推送注册失败	确认AGC已建应用、APPID已写入签名Profile
预置包被系统忽略不安装	preinstall目录包名与AGC bundleName不符，或缺少config.json中reqPermissions
换电脑后签名报错	新DevEco需重新下载同一AGC项目的调试证书（Signing Config → Download Certificate）
想复用旧APPID	同一Project下可新建应用，但bundleName必须唯一；跨Project不能复用APPID

---

五、总结：预置应用APPID法则

1. 先AGC后编码：任何HarmonyOS应用（含预置未上架）第一步都是在AGC创建应用拿APPID

2. bundleName铁律：AGC建应用时填的包名 = module.json5中bundleName= 预置白名单包名

3. 签名绑定APPID：用AGC关联的调试/发布证书打HAP，APPID自动嵌入

4. 不上架也可调系统能力：只要APPID合法、签名匹配、权限在白名单内，预置应用可正常使用Reminder/Push等能力

核心法则：在HarmonyOS 6预置应用开发中，"没有AGC应用ID的包，不是合法应用"——无论上不上架市场，这一步都不能省。

©著作权归作者所有，如需转载，请注明出处，否则将追究法律责任。