HarmonyOS Profile 签名链路实战debug/release、开放能力与 11111002Project028 接入系统代理提醒后真正卡住发布链路的不是一行 ArkTS 代码而是 Profile、证书、开放能力和 AGC 包签名之间的匹配关系。module.json5里声明了PUBLISH_AGENT_REMINDER不代表 release 包已经具备这个能力本地有 release Profile也不代表它和当前签名证书匹配。这一章沿 Project028 的实际交付链路拆解debug Profile 用来真机调试release Profile 用来 AGC 上架包开放能力审批通过后要重新生成 Profile11111002 Certificates error不是普通编译错误而是证书链和 Profile 不一致。把这条链路理顺后面的构建、上传、审核才不会互相打架。debug Profile 和 release Profile 不是一回事HarmonyOS 项目里经常会同时存在 debug 和 release 两套签名材料。它们解决的问题不同debug Profile - 本地调试 - 真机安装 - DevEco Run - 快速验证系统能力release Profile - 正式签名 - assembleApp - AGC 上传 - 审核与上架Project028 的提醒能力先在 debug 链路里验证设备能安装、权限能声明、系统能返回systemReminderId。但这只能证明开发链路可用。真正提交 AGC 的.app仍然要看 release Profile 是否包含同样的开放能力。权限声明不等于 Profile 权益module.json5负责声明应用要用哪些权限。Project028 的提醒权限写在这里{ name: ohos.permission.PUBLISH_AGENT_REMINDER }这一步是必要条件但不是充分条件。对需要平台审批的能力还要看 Profile 里是否包含对应能力。如果只改module.json5不重新生成包含权益的 Profile构建或运行阶段仍然可能失败。可以把关系拆成三层module.json5 requestPermissions - Profile capability entitlement - signed HAP / APP embedded profile三层缺一不可。缺第一层应用没有声明缺第二层签名材料不允许缺第三层最终包里没有带上正确权益。agentreminder 在 Profile 能力树里代理提醒能力不是普通页面配置。Project028 审批通过后需要在 Profile 能力树里看到对应开放能力。排查时不要只搜索权限名也要搜索能力服务名。PUBLISH_AGENT_REMINDER agentreminder app-services-capabilities com.huawei.service.notification.agentreminder排查思路可以写成AGC 能力审批通过 - 重新生成 debug Profile - 重新生成 release Profile - DevEco / hvigor 使用新 Profile - 重新构建 HAP / APP如果审批后继续使用旧 Profile代码看起来正确包也可能构建但系统能力不一定生效。build-profile 只检查字段不公开密钥build-profile.json5里会配置签名信息。排查时只看字段是否指向正确材料不在文章、日志和交接文档里公开密码、私钥路径或证书敏感内容。应关注这些字段signingConfigs material.certpath material.profile material.signAlg products.signingConfig检查目标是确认当前构建模式使用哪套签名 清单如下 assembleHap --mode module - 是否走 debug signingConfig assembleApp - 是否走 release signingConfig这一步只需要记录“debug/release 是否指向预期材料”不需要把材料内容贴出来。11111002 不是普通语法错误Project028 的 release 构建曾经遇到 清单如下 ERROR: 11111002 Certificates error这个错误不要按 ArkTS 语法问题处理。它通常意味着证书、私钥、Profile 之间的绑定关系不一致或者 release Profile 绑定了一个本机没有对应私钥的证书。排查表可以这样写 清单如下 现象11111002 Certificates error 第一判断签名链问题 不优先改页面代码、Service 逻辑、权限文案 优先看release Profile 绑定证书、本地 release 私钥、证书指纹这类错误如果误判为代码问题会把时间浪费在无关文件上。证书链要成对匹配release 包签名需要一组能互相匹配的材料。可以抽象成 清单如下 private key - certificate - release Profile - signed app如果 release Profile 绑定的是证书 A但本地构建使用的是证书 B 的私钥就会失败。解决方向不是随便换一个 Profile而是让 Profile 和本地实际能使用的 release 证书链重新匹配。修复后再运行.\hvigorw.bat assembleApp只有 release app 成功产出AGC 上传链路才有继续推进的基础。Profile 更新后要重新安装验证debug Profile 更新后不能只看文件时间。要重新构建并安装到真机上确认系统看到的是新权限和新能力。设备预检仍然先跑hdc list targets -v再确认/data/local/tmp可写hdc shell echo write_ok /data/local/tmp/codex_write_test cat /data/local/tmp/codex_write_test rm /data/local/tmp/codex_write_test然后安装新包hdc install -r .\entry\build\default\outputs\default\entry-default-signed.hap安装后再看应用声明权限hdc shell bm dump -n com.example.project028这里重点看reqPermissions里是否能看到ohos.permission.PUBLISH_AGENT_REMINDER以及功能路径是否能真正返回系统提醒 id。assembleHap 和 assembleApp 的定位不同assembleHap和assembleApp经常被混用但排查发布问题时要分清。 清单如下 assembleHap: - 验证 entry 模块 - 适合真机安装 - 适合页面和系统能力本地调试 清单如下 assembleApp: - 生成 AGC 上传包 - 走 release 签名 - 更接近审核链路如果本地 HAP 能安装但.app构建失败问题大概率在 release 签名、Profile 或打包链路不应回头大改业务代码。AGC 版本元数据也要同步签名链路修好后还要确认版本元数据。Project028 的基础版本信息在AppScope/app.json5中{ bundleName: com.example.project028, versionCode: 1000000, versionName: 1.0.0 }AGC 上传时要确认当前包和版本页一致 清单如下 bundleName 一致 versionCode 符合平台要求 versionName 显示正确 package 上传成功 version 绑定到新 package如果 AGC 提示版本冲突、包名不一致或证书不一致先看元数据和签名链不要先改页面。内嵌 Profile 要跟最终包一致排查 Profile 问题时不能只看磁盘上的 Profile 文件。最终包里嵌入的 Profile 才是系统和 AGC 真正读取的内容。可以把验证目标写成 清单如下 source profile - hvigor signing config - signed hap/app - embedded profile - AGC validation本地需要确认构建过程没有继续引用旧 Profile。常见原因包括 DevEco 缓存、配置指向旧路径、复制了新文件但 product 仍绑定旧 signingConfig。 清单如下 文件换了但配置没换无效 配置换了但没重新构建无效 重新构建了但上传旧包无效 上传新包但版本未绑定无效这四种情况都曾经在发布链路里出现过。设备侧验证看真实系统结果Profile 和权限链路最终要落到设备侧结果。Project028 代理提醒的关键证据是系统返回systemReminderId并且通知可见。服务层成功结果类似return { status: scheduled, systemReminderId: reminderId };页面保存后不应只展示本地保存成功而要根据服务层结果提示 清单如下 scheduled - 提醒已开启 disabled - 提醒已关闭 permissionDenied - 需要通知或代理提醒能力 failed - 展示系统错误摘要这能帮助审核和测试区分“功能没保存”和“系统能力没调度成功”。失败时只改一层签名、Profile、权限、代码经常交织在一起。排查时要一次只改一层才能知道哪一步真正生效。推荐顺序 清单如下 1. 确认 module.json5 权限声明 2. 确认 AGC 能力审批状态 3. 重新生成 debug Profile 4. debug HAP 真机验证 5. 重新生成 release Profile 6. assembleApp 7. AGC 上传和绑定如果第二步还没完成不要在第六步反复构建如果第六步报 11111002不要改第一步权限名。release 签名三件套release 链路最少要看三件东西 清单如下 release private key release certificate release Profile它们必须来自同一条链。Project028 的修复方向是让 release Profile 重新绑定本机实际可用的 release 证书而不是替换业务代码。可以把风险记录成 清单如下 风险Profile 绑定证书与本地私钥不匹配 影响assembleApp 失败AGC 无法上传新包 修复重新生成绑定正确证书的 release Profile 验证assembleApp 通过并产出 signed app这个记录比只写“签名失败已修复”更利于后续接手。上架链路必须分阶段说清楚签名修复完成后对外状态也要分阶段描述。 清单如下 release Profile 已更新 release app 已构建 AGC 包已上传 AGC 版本已绑定 AGC 已提交预审 平台审核结论待返回不能把“release app 已构建”说成“审核已通过”。审核结论只能来自 AGC 平台。Project028 的记录里会保留 清单如下 package: Project028-default-signed.app upload status: success bind status: bound review status: pre-review / reviewing / rejected / passed这样状态清楚后面追问题时不会混淆。交接清单Profile 和签名链路修复完成后交接至少包含 清单如下 - 权限声明已确认 - 开放能力审批已确认 - debug Profile 已重新生成 - debug HAP 已真机验证 - release Profile 已重新生成 - release 证书链匹配 - assembleApp 已通过 - AGC 上传包名和版本已记录 - AGC 当前版本已绑定新包 - 审核状态已标注交接文档里不写私钥密码不贴证书敏感内容只写验证结论和可追溯的非敏感证据。本地缓存也会制造假象Profile 和签名材料更新后DevEco、hvigor 和中间产物缓存都有可能让人误判。文件已经替换不代表当前构建一定读到了新文件。Project028 在处理签名链路时会把“换文件”和“构建使用新文件”分开验证。推荐检查顺序 清单如下 1. build-profile.json5 指向新 Profile 2. 关闭旧的构建进程或 daemon 干扰 3. 重新执行 assembleHap / assembleApp 4. 检查输出包时间 5. 安装或上传的就是这个输出包如果担心缓存干扰可以做一次轻量清理但不要在没有证据时删除大范围工程目录.\hvigorw.bat --stop-daemon构建成功后再看输出包时间Get-Item .\build\outputs\default\Project028-default-signed.app这里的目标是确认自己上传的是新产物而不是昨天留下的旧包。能力审批通过后要同时覆盖两套包代理提醒这类能力审批通过后只更新 debug Profile 是不够的。debug 能跑只能说明开发设备可用release 上架包仍然可能缺权益。Project028 会把审批后的动作拆成两条线 清单如下 debug line: regenerate debug Profile build signed HAP install to device verify systemReminderId 清单如下 release line: regenerate release Profile check certificate binding build signed APP upload to AGC bind current version两条线都完成才算能力链路完整。只跑其中一条最终都会在真机验证或平台审核阶段暴露问题。证书错误和权限错误要分开发布排障里常见两个错误方向证书错误和权限错误。它们表现都可能是“包不可用”但根因不同。 清单如下 权限错误 - module.json5 没声明 - Profile 没开放能力 - 设备权限未授权 - 系统 API 返回 permission denied 清单如下 证书错误 - Profile 绑定证书不一致 - 私钥和证书不匹配 - release signingConfig 指向错误 - assembleApp 报 11111002如果日志里直接出现11111002 Certificates error先走证书链如果运行时返回权限拒绝再看权限声明、Profile 权益和用户授权。不要把 Profile 当成普通资源文件Profile 不是图片、JSON 配置或普通资源文件。它和包名、证书、能力、设备调试权限都有关系。复制一个看起来更新的文件到项目里不等于签名链路成立。正确的处理方式是 清单如下 从 AGC 按当前应用和证书生成 - 放到签名配置引用路径 - 确认 product 使用对应 signingConfig - 重新构建 - 验证输出包如果只是把文件丢进目录却没有修改build-profile.json5的引用路径构建仍然可能使用旧 Profile。反过来如果修改了引用路径但这个 Profile 绑定的是另一个 release 证书也会在签名阶段失败。版本绑定是最后一道确认Profile 修复、release 构建通过、AGC 上传成功之后还差最后一步当前版本必须绑定这个新包。很多发布链路的问题就卡在这里。可以把 AGC 状态写成四列 清单如下 package uploaded: yes / no package file: Project028-default-signed.app version bound: yes / no review submitted: yes / no只有四列都为yes才能说平台开始按新包审核。否则仍然只是本地或素材库状态。失败记录要能复盘11111002这类问题处理完后最好把失败和修复写成一段可以复盘的记录 清单如下 Root Cause: release Profile 绑定的证书与本地 release 私钥不匹配。 Fix: 重新生成绑定当前 release 证书的 release Profile并让 release signingConfig 指向它。 Validation: assembleApp 通过产出 Project028-default-signed.app。 Risk: AGC 平台仍需确认当前版本已经绑定新包。这类记录比“重签名后好了”更有价值。下次遇到相同错误可以直接从证书链开始查。从 Profile 问题回到运行时能力Profile 修好以后还要回到运行时能力验证。Project028 的代理提醒不是为了通过构建而是要让用户真正收到系统提醒。所以签名链路通过后还要跑功能路径。验证路径可以写成 清单如下 打开应用 - 进入提醒设置 - 开启提醒 - 设置一个临近时间 - 保存 - 观察 systemReminderId - 等待系统通知如果构建通过但运行时仍失败要重新区分 清单如下 构建通过签名链路基本成立 权限拒绝看用户授权和系统能力授权 没有通知看 notificationManager 权限和提醒请求 没有 systemReminderId看 publishReminder 返回错误这能避免把运行时问题再次误判成 Profile 问题。不同错误要有不同交互反馈代理提醒涉及多个失败点页面不能只显示一个通用失败。Project028 更适合按服务层状态映射文案。 清单如下 permissionDenied: 当前无法发布系统提醒请先开启通知权限或确认应用能力。 failed: 系统提醒调度失败请稍后重试。 scheduled: 提醒已开启。 disabled: 提醒已关闭。如果系统返回的是提醒数量上限文案可以提示已经尝试清理旧提醒 清单如下 系统提醒数量已达到上限已清理本应用旧提醒请重新保存。文案准确后审核员看到的就不是“保存成功但没有提醒”而是明确的系统能力状态。Profile 变更要纳入版本记录Profile 变更虽然不一定改业务代码但它会影响最终包能力。Project028 会把这类变更写入交付记录而不是只保存在本地文件夹里。记录字段可以包括 清单如下 profileType: debug / release capability: agentreminder bundleName: com.example.project028 signingConfig: debug / release validation: hdc install / assembleApp / AGC upload这里仍然不写证书密码和私钥路径只保留非敏感的追溯信息。后续如果 AGC 再次打回可以快速判断当前平台审核的是哪一次 Profile 变更之后的包。处理 11111002 的最小闭环遇到11111002时Project028 的最小闭环不是“换一个签名文件再试”而是按证据确认三件事。 清单如下 1. release Profile 绑定的证书是谁 2. 本地 release signingConfig 使用的证书和私钥是谁 3. assembleApp 实际读取的是哪一个 Profile三件事一致后再构建.\hvigorw.bat assembleApp构建通过后再进入 AGC 清单如下 upload app - bind package - submit review - wait platform result如果只做第一步构建不完成 AGC 绑定审核平台仍然可能看不到新包。和普通页面问题的处理差异页面问题通常可以通过源码、预览、真机点击闭环关闭Profile 问题必须覆盖构建和平台链路。两者的验收方式不同。 清单如下 页面问题 source change - build - install - click path - screenshot or behavior evidence 清单如下 Profile 问题 profile regeneration - signing config - assembleApp - upload - bind version - platform validation把这两类问题混在一起会让验证缺口很大。Project028 的做法是把它们放在同一份交付记录里但分别写验证结果。敏感信息处理边界签名排查不可避免会看到证书、Profile、别名和密码字段。记录时要坚持一个边界能证明状态但不暴露秘密。可以写 清单如下 release Profile 已重新生成 release signingConfig 已指向新 Profile assembleApp 已通过不应该写 清单如下 私钥完整路径 证书密码 keystore 密码 profile 原文内容对发布型项目来说这个边界和代码修复同样重要。最后看审核闭环是否一致Profile 和签名链路都修完后还要把审核闭环再走一遍。Project028 这类已经进入 AGC 的项目不能停在本地构建通过。闭环检查可以写成 清单如下 source: 当前源码包含权限声明和服务层处理 profile: debug / release 都包含已审批能力 signing: release 证书链匹配 package: assembleApp 产出新包 platform: AGC 上传并绑定当前版本 review: 当前版本已重新提交其中任何一项缺失都要在交付里标成not done或pending。例如 AGC 已上传但未绑定就只能写“包已上传”不能写“审核包已更新”。这条闭环也能帮助区分责任边界 清单如下 本地失败看代码、Profile、签名配置 上传失败看包格式、证书、版本号 绑定失败看 AGC 版本页和包状态 审核失败回到报告附件和复现路径排查时始终按当前失败层处理不跨层猜。对交付负责人来说最终结论也要保持分层本地能构建、真机能运行、平台能上传、版本已绑定、审核已提交分别代表不同阶段。只有这些阶段全部闭合Profile 修复才真正进入可审核状态。小结HarmonyOS 的 Profile 和签名链路要按工程状态来理解。module.json5是权限声明Profile 是平台权益证书链决定构建能不能签出包AGC 版本绑定决定审核看到哪一个包。任何一层缺失都可能表现成“代码明明对了但平台不通过”。Project028 的处理方式是先在 debug 链路验证能力再把同样的权益同步到 release Profile遇到11111002时回到证书链检查最后用assembleApp和 AGC 版本绑定确认发布链路。这样写出的交付记录既能保护敏感信息又能让后续排查有证据可追。