在这里插入图片描述

你是不是也在想——“鸿蒙这么火,我能不能学会?”
答案是:当然可以!
这个专栏专为零基础小白设计,不需要编程基础,也不需要懂原理、背术语。我们会用最通俗易懂的语言、最贴近生活的案例,手把手带你从安装开发工具开始,一步步学会开发自己的鸿蒙应用。
不管你是学生、上班族、打算转行,还是单纯对技术感兴趣,只要你愿意花一点时间,就能在这里搞懂鸿蒙开发,并做出属于自己的App!
📌 关注本专栏《零基础学鸿蒙开发》,一起变强!
每一节内容我都会持续更新,配图+代码+解释全都有,欢迎点个关注,不走丢,我是小白酷爱学习,我们一起上路 🚀

前言

在 HarmonyOS 应用开发过程中,很多开发者都会遇到这样一个现象:在 module.json5 中声明了一个权限,然后在 DevEco Studio 中勾选了 “Automatically generate signature”(自动签名),但编译打包时却抛出了签名校验失败或 Profile 文件不匹配的错误;或者打出的包在安装时报错,提示权限未被授权。

同样是权限,为什么有的权限在 module.json5 里写完就能用,有的权限却必须去 AppGallery Connect(AGC)后台申请并配置特殊的签名文件?

本文将围绕 HarmonyOS 的权限等级划分、ACL(Access Control List)机制、Provision Profile(.p7b)文件的作用,以及 DevEco Studio 自动签名与手动签名的区别进行深入拆解。

一、鸿蒙权限体系的核心逻辑:APL 等级与授予方式

要理解 ACL 权限,首先需要理清 HarmonyOS 官方对应用权限的维划分。HarmonyOS 从两个独立维度对权限进行了定义:应用APL等级 和 权限授予方式。

1. 应用 APL 等级(Application Privilege Level)

HarmonyOS 系统将应用划分为了三个 APL 等级,由低到高分别为:

  • normal(普通应用):绝大多数上架华为应用市场的第三方应用都属于这个等级。
  • system_basic(系统基础应用):系统基础服务及核心应用,例如系统设置、UI界面等。
  • system_core(系统核心应用):包含系统最底层核心能力的应用,例如媒体服务、通信服务。

与此对应,系统 API 和权限也标注了对应的 APL 等级要求。原则上,普通应用(normal)只能申请 normal 等级的权限,无法直接申请 system_basic 或 system_core 等级的权限。

2. 权限授予方式(grant_mode)

在配置文件 module.json5 中,权限的 grant_mode 决定了权限何时向用户授权:

  • system_grant(系统授权):应用安装时由系统自动授予,无需弹窗提示用户(例如网络访问权限 ohos.permission.INTERNET)。
  • user_grant(用户授权):应用运行过程中,必须通过调用 API 动态弹窗,由用户手动点击允许后方可使用(例如相机权限 ohos.permission.CAMERA)。

二、为什么有的权限声明了也不能用?受限权限与 ACL 机制

在实际开发中,部分能力虽然属于普通应用可能用到的场景,但涉及高敏感数据或系统核心安全。华为官方将其划分为受限权限(Restricted Permissions),或者该权限本身的 APL 等级高于应用自身的 APL 等级(例如需要 system_basic 等级)。

1. 什么是 ACL(Access Control List)?

ACL(访问控制列表) 是 HarmonyOS 针对权限越级申请提供的一种官方授权通道。

当一个 normal 等级普通应用,因为特定合理业务场景(例如剪贴板读取、特定设备硬件访问等),必须使用高于 normal 等级或属于系统严格管控的受限权限时,无法仅通过 module.json5 配置文件直接获取。此时,必须通过 ACL 机制在应用的**签名 Profile( provisioning profile )**中明确添加授权。

2. 受限权限的约束逻辑

如果没有在 Profile 中配置 ACL 授权,直接在 module.json5 中声明受限权限,会触发以下逻辑拦截:

  1. 编译/签名阶段:DevEco Studio 校验签名 Profile 文件时,发现 Profile 里的 allowed-acls 列表并不包含该受限权限,直接终止编译并报错。
  2. 安装阶段:即使绕过编译,系统包管理器(bm/pms)在解析安装包签名信息时,若校验 Profiles 签名数据未包含对应的 ACL 授权,将拒绝安装(报错 code: ERR_APP_EXEC_INSTALL_FAILED_PROFILE_NOT_ALLOWED)。

三、DevEco Studio 自动签名的能力边界

DevEco Studio 提供了极为便捷的 “Automatically generate signature”(自动签名) 功能,开发者只需要登录华为账号,IDE 就会自动向 AppGallery Connect 请求生成调试证书(.cer)和调试 Profile 文件(.p7b)。

自动签名的局限性

自动签名只能用于申请常规的非受限权限(即 normal 等级且非受限的权限)。

自动签名背后的原理是:DevEco Studio 向 AGC 申请的是一个通用默认调试 Profile。为了保证系统安全性,AGC 自动签发给 IDE 的通用调试 Profile 中,allowed-acls 列表默认为空。

这就解释了本文开头提到的现象:
一旦你在 module.json5 中加入了一个受限权限(例如受限的系统能力权限),再点击 DevEco Studio 的自动签名,系统就会提示 Profile 校验失败。因为自动生成的 Profile 无法包含该受限权限的 ACL 授权。

四、Profile 文件的解密:临时 Profile 与正式 Profile

Provision Profile(扩展名为 .p7b)是鸿蒙应用包的安全合规通行证。它是一个经过 PKCS#7 签名的结构化数据文件,内部包含了应用包名、签名证书公钥指纹、设备 UUID 列表,以及最关键的 permissions 与 acls 授权字段。

1. Profile 的分类与生命周期

特性调试 Profile(Debug Profile / 临时)发布 Profile(Release Profile / 正式)
申请渠道AGC 平台 -> 证书、App ID 及 Profile 管理AGC 平台 -> 应用上架发布流程
设备限制严格限制受信任的真机 UDID 列表无限制(通过应用市场安装)
ACL 权限申请开发者在 AGC 后台手动勾选调试所需的受限权限即可生成必须提交完整的业务申请说明,通过 AGC 人工审核后签发
用途本地真机开发调试、自动化测试打包 App / Bundle 上架 AppGallery

五、受限权限配置与申请的全流程实践

下面以一个需要配置 ACL 权限的典型场景为例,展示从配置文件到 AGC 签名配置的完整流程。

1. 配置文件 module.json5 的写法

以申请剪贴板读取权限 ohos.permission.READ_PASTEBOARD 为例(在特定 API Level 或受限场景下需要关注其权限属性),需要在 requestPermissions 中正确写明权限定义:

{
  "module": {
    "name": "entry",
    "type": "entry",
    "srcEntry": "./ets/Application/MyAbilityStage.ets",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.READ_PASTEBOARD",
        "reason": "$string:reason_read_pasteboard",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      }
    ]
  }
}

关键字段解释:

  • name: 权限的精确名称,必须与官方 API Reference 保持完全一致(大小写敏感)。
  • reason: 当权限属于 user_grant 时必须配置该字段,指向 string.json 中的多语言资源说明,用于在弹窗时告知用户申请原因。
  • usedScene: 说明使用该权限的场景和组件。

2. 调试阶段:从自动签名切换为手动签名(Manual Signing)

当 module.json5 中包含受限权限后,自动签名将失效,必须按照以下步骤改为手动签名配置:

  1. 登录 AGC 控制台:进入“用户与权限”或“证书、App ID 及 Profile 管理”。

  2. 申请 ACL 权限配置:在目标应用的调试 Profile 设置中,找到“受限权限”或“ACL 权限”勾选框,将项目需要的受限权限加入该 Profile 的授权列表中。

  3. 下载 .p7b 文件:生成并下载这个包含了 ACL 授权的临时 Debug Profile。

  4. DevEco Studio 配置:

    • 取消勾选 “Automatically generate signature”。
    • 分别指定准备好的 .p12 证书文件、密码、.cer 证书文件以及刚才下载的包含 ACL 授权的 .p7b 文件。

六、排查清单与踩坑经验

当遇到权限相关构建错误或运行期异常时,可按照以下顺序依次进行排查:

[检查签名配置] -> [核对 module.json5] -> [解析 Profile 文件] -> [检查动态授权代码]

1. 编译构建报错:Profile error 或 Signature verify failed

  • 优先检查:是否开启了自动签名。如果使用了受限权限,必须关闭自动签名,改用手动配置包含 ACL 字段的 .p7b 文件。
  • 核对 Bundle Name:Profile 文件生成时绑定的 Bundle Name(包名)必须与 AppScope/app.json5 中的 bundleName 严格一致。

2. 安装报错:ERR_APP_EXEC_INSTALL_FAILED_PROFILE_NOT_ALLOWED

  • 检查 UDID:如果是调试包,检查当前连接的鸿蒙真机 UDID 是否已加入到该 Debug Profile 文件中。
  • 检查 ACL 授权字段:可以使用解压工具查看 .p7b 文件中的文本内容,核对 allowed-acls 数组中是否真正包含了你在 module.json5 里申请的那个权限名称。

3. 运行期报错:Permission denied

  • 检查 Grant Mode:若权限属于 user_grant(用户授权),光在 module.json5 中声明是不够的,必须在 ArkTS 代码中显式调用 abilityAccessCtrl.createAtManager().requestPermissionsFromUser() 触发拉起用户授权弹窗。

七、总结与开发思考

  1. 区分普通权限与受限权限:普通权限可以通过 DevEco Studio 自动签名快速开发调试;受限权限(或高于应用 APL 等级的权限)必须走 ACL 授权流程。
  2. 理解 Profile 的安全锁作用:Profile 文件不仅仅是用于设备调试绑定,它更是在打包层面限制应用越权调用的核心安全屏障。
  3. 上架前预留审核时间:正式发布应用时,涉及 ACL 的受限权限需要经过 AppGallery Connect 的人工合规审核,务必提前准备好合理的业务使用场景说明与录屏材料,避免因权限问题影响发布排期。

你在开发过程中是否遇到过因为签名配置问题导致受限权限无法调用的情况?欢迎在评论区分享你的排查经历与解决方案。

❤️ 如果本文帮到了你…

  • 请点个赞,让我知道你还在坚持阅读技术长文!
  • 请收藏本文,因为你以后一定还会用上!
  • 如果你在学习过程中遇到bug,请留言,我帮你踩坑!
Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐