第4章权限声明与配置

4. 权限声明与配置：module.json5配置、权限标签语法、权限组概念

权限管理，说白了就是应用能不能碰用户隐私的那道门。我刚开始接触鸿蒙时，觉得这玩意儿不就是写几行配置嘛，后来踩了坑才明白——权限声明写不对，应用直接闪退，用户还会投诉你乱要权限。今天咱们就把这块彻底捋清楚。

4.1 module.json5 里的权限声明

每个鸿蒙应用都有一个 module.json5 文件，它就像应用的身份证。权限声明就写在这里面。我个人习惯把它放在 entry/src/main/module.json5 路径下。

先看一个最基础的配置示例：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "MainAbility",
    "deviceTypes": ["phone", "tablet"],
    "requestPermissions": [
      {
        "name": "ohos.permission.CAMERA",
        "reason": "$string:camera_reason",
        "usedScene": {
          "abilities": ["MainAbility"],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.MICROPHONE",
        "reason": "$string:microphone_reason",
        "usedScene": {
          "abilities": ["MainAbility"],
          "when": "always"
        }
      }
    ]
  }
}

这里有几个关键字段，我一个个说：

name：权限的名称，必须写全。比如 ohos.permission.CAMERA，少一个字母都不行。我曾经因为把 CAMERA 拼成 CAMARA，调试了整整一下午。
reason：为什么要这个权限。这个字段在 API 9 之后是强制的，用户会在弹窗里看到。写清楚点，比如“用于扫码识别商品”，别写“为了更好的体验”这种废话。
usedScene：权限在哪个页面用、什么时候用。这里分 abilities（页面列表）和 when（使用时机）。when 有两个值：inuse 表示前台使用，always 表示后台也能用。

⚠️ 注意： 敏感权限（比如位置、相机、麦克风）必须填写 reason 和 usedScene。不写的话，应用在华为应用市场上架时会直接被驳回。我有个同事就因为这个被拒了三次。

4.2 权限标签语法详解

权限标签的语法其实不复杂，但细节很多。咱们拆开来看：

4.2.1 权限名称的命名规则

鸿蒙的权限命名遵循 ohos.permission.XXX 的格式。比如：

ohos.permission.INTERNET —— 网络访问
ohos.permission.READ_CONTACTS —— 读取联系人
ohos.permission.ACCESS_FINE_LOCATION —— 精确定位

你想想看，这种命名方式其实挺清晰的。一看就知道是哪个系统、哪类权限。我个人建议，写的时候直接去官方文档复制，别手敲。手敲容易出错，尤其是 ACCESS_BACKGROUND_LOCATION 这种长名字。

4.2.2 reason 字段的写法

reason 字段支持两种写法：

直接写字符串：比如 "reason": "用于拍照上传头像"
引用资源文件：比如 "reason": "$string:camera_reason"，然后在 string.json 里定义多语言文案

我建议用第二种方式。为什么呢？因为如果你的应用要出海，多语言支持是必须的。直接在 module.json5 里写死字符串，后面改起来很麻烦。

4.2.3 usedScene 的配置细节

usedScene 里的 abilities 是一个数组，可以写多个页面。比如：

"usedScene": {
  "abilities": ["MainAbility", "CameraAbility", "PhotoAbility"],
  "when": "inuse"
}

这里要注意：abilities 里写的是 Ability 的名称，不是页面路由。我刚开始搞混过，结果权限一直没生效。

💡 小技巧： 如果你的权限在多个页面都用到了，建议把所有页面都列出来。这样用户在授权时能看到“这个权限会在哪些页面使用”，信任感会强很多。

4.3 权限组概念

权限组，说白了就是把几个相关的权限打包在一起。用户授权时，只需要同意一次，组内的所有权限就都拿到了。

举个例子，位置信息权限组包含：

权限名称	说明
ohos.permission.LOCATION	模糊位置（基于基站/WiFi）
ohos.permission.ACCESS_FINE_LOCATION	精确定位（基于GPS）
ohos.permission.ACCESS_BACKGROUND_LOCATION	后台定位

用户如果授权了 ohos.permission.LOCATION，系统会自动把 ACCESS_FINE_LOCATION 也带上。但 ACCESS_BACKGROUND_LOCATION 需要单独申请，因为后台定位更敏感。

为什么会这样设计？我理解是，权限组是为了减少弹窗次数。你想想看，如果每个权限都弹一次窗，用户早就烦死了。但敏感权限（比如后台定位、读取短信）必须单独申请，这是为了保护隐私。

常见的权限组还有：

相机组：CAMERA + FLASHLIGHT
麦克风组：MICROPHONE + RECORD_AUDIO
联系人组：READ_CONTACTS + WRITE_CONTACTS

  📌 核心要点： 权限组只对用户授权时的体验有影响。你在 module.json5 里声明时，还是要逐个写清楚。系统会自动识别哪些权限属于同一个组。

4.4 实战中的避坑指南

嗯，这里我要多说几句。权限声明这块，坑真的不少。

我曾经遇到过一个问题：应用在调试模式下一切正常，但打包上架后，用户反馈说相机打不开。查了半天，发现是 module.json5 里少写了一个 usedScene 字段。调试模式下系统会放宽检查，但正式包不会。

所以我的建议是：

写完权限声明后，用 DevEco Studio 的“检查”功能跑一遍。它会提示你哪些权限缺少必要字段。
在真机上测试时，把应用卸载重装一次。因为权限配置只在首次安装时读取，覆盖安装可能不会触发重新授权。
对于敏感权限，一定要写 reason。不写的话，系统会弹出一个默认的“应用需要此权限”，用户一看就觉得不靠谱。

4.5 知识体系总览

为了让你更直观地理解权限声明与配置的整体逻辑，我画了一张图：

这张图把权限声明与配置的核心脉络串起来了。从 module.json5 出发，分三条线：权限声明怎么写、标签语法有哪些细节、权限组怎么理解。最后落到一个核心原则上——按需声明、明确理由、区分场景。

好了，权限声明与配置这块就讲到这里。记住一句话：权限声明不是写给自己看的，是写给系统和用户看的。写清楚了，系统不报错，用户不反感，应用上架也顺利。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录

4. 权限声明与配置：module.json5配置、权限标签语法、权限组概念

4.1 module.json5 里的权限声明

4.2 权限标签语法详解

4.2.1 权限名称的命名规则

4.2.2 reason 字段的写法

4.2.3 usedScene 的配置细节

4.3 权限组概念

4.4 实战中的避坑指南

4.5 知识体系总览