youxi-app/uni_modules/m-permission-manager/权限配置说明.md

m-permission-manager 权限配置说明

本文档说明集成本插件时，各端需要修改哪些文件、如何配置权限，以及插件内置配置文件的作用。

---

1. 配置总览

平台	配置文件	配置方	说明
Android	宿主 manifest.json	集成者	声明 android.permission.*
iOS	宿主 manifest.json	集成者	声明 NS*UsageDescription
Harmony	插件 utssdk/app-harmony/module.json5（可选：harmony-configs/entry/src/main/module.json5）	插件内置为主，集成者可切换 full 版或宿主覆盖

插件负责运行时检查与申请；Android / iOS 的静态声明必须由宿主项目在 manifest 中完成。Harmony 权限由插件 module 合并进宿主包，集成者按需切换 normal / full 版本。

---

2. Android 配置

2.1 配置文件

路径：项目根目录 manifest.json
节点：app-plus.distribute.android.permissions

{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.CAMERA\"/>",
          "<uses-permission android:name=\"android.permission.RECORD_AUDIO\"/>",
          "<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\"/>",
          "<uses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\"/>",
          "<uses-permission android:name=\"android.permission.READ_CONTACTS\"/>",
          "<uses-permission android:name=\"android.permission.BLUETOOTH_CONNECT\"/>",
          "<uses-permission android:name=\"android.permission.BLUETOOTH_SCAN\"/>",
          "<uses-permission android:name=\"android.permission.READ_MEDIA_IMAGES\"/>",
          "<uses-permission android:name=\"android.permission.READ_MEDIA_VIDEO\"/>"
        ]
      }
    }
  }
}

2.2 统一 Key 与 Android 权限映射

插件 Key	Android 权限	备注
camera	CAMERA
photoLibrary	READ_MEDIA_IMAGES（API 33+）或 READ_EXTERNAL_STORAGE	插件按 SDK 自动选择
storage	READ_MEDIA_IMAGES + READ_MEDIA_VIDEO（API 33+）或 WRITE/READ_EXTERNAL_STORAGE
readStorage	同 photoLibrary / 媒体读权限
location	ACCESS_FINE_LOCATION
coarseLocation	ACCESS_COARSE_LOCATION
microphone	RECORD_AUDIO
contacts	READ_CONTACTS
writeContacts	WRITE_CONTACTS
bluetooth	BLUETOOTH_CONNECT + BLUETOOTH_SCAN（API 31+）或 BLUETOOTH + BLUETOOTH_ADMIN
phone	CALL_PHONE
phoneState	READ_PHONE_STATE
sms	SEND_SMS
readSms	READ_SMS
receiveSms	RECEIVE_SMS
overlay	无 manifest 条目	通过 Settings.canDrawOverlays 检查
writeSettings	无 manifest 条目	通过 Settings.System.canWrite 检查

2.3 注意

• 只声明业务使用的权限，避免过度申请
• Android 13+ 媒体权限使用 READ_MEDIA_*；插件仅在 targetSdkVersion >= 33 时动态申请新媒体权限，否则回退 READ_EXTERNAL_STORAGE（兼容 targetSdk 偏低的自定义基座）
• overlay、writeSettings 需在 manifest 声明对应 capability 后，通过插件跳转系统设置页授权

---

3. iOS 配置

3.1 配置文件

路径：项目根目录 manifest.json
节点：app-plus.distribute.ios.privacyDescription

{
  "app-plus": {
    "distribute": {
      "ios": {
        "privacyDescription": {
          "NSCameraUsageDescription": "需要使用相机进行拍照",
          "NSMicrophoneUsageDescription": "需要使用麦克风进行录音",
          "NSPhotoLibraryUsageDescription": "需要访问相册以选择图片",
          "NSPhotoLibraryAddUsageDescription": "需要保存图片到相册",
          "NSLocationWhenInUseUsageDescription": "需要获取位置信息",
          "NSContactsUsageDescription": "需要访问通讯录",
          "NSBluetoothAlwaysUsageDescription": "需要使用蓝牙连接周边设备"
        }
      }
    }
  }
}

3.2 统一 Key 与 Info.plist 键映射

插件 Key	Info.plist 键	备注
camera	NSCameraUsageDescription
photoLibrary	NSPhotoLibraryUsageDescription
storage	NSPhotoLibraryUsageDescription 或 NSPhotoLibraryAddUsageDescription	映射到相册
readStorage	NSPhotoLibraryUsageDescription	映射到相册
location	NSLocationWhenInUseUsageDescription
coarseLocation	NSLocationWhenInUseUsageDescription	与精确定位共用
microphone	NSMicrophoneUsageDescription
contacts	NSContactsUsageDescription
writeContacts	NSContactsUsageDescription	读写共用
bluetooth	NSBluetoothAlwaysUsageDescription	必须配置，否则 App 设置页无蓝牙开关

3.3 iOS 蓝牙特别说明

iOS 蓝牙涉及两个独立概念：

概念	设置路径	配置要求
系统蓝牙开关	设置 → 蓝牙	无需 manifest，用户手动打开
App 蓝牙授权	设置 → 本 App → 蓝牙，或 设置 → 隐私与安全性 → 蓝牙	需 NSBluetoothAlwaysUsageDescription + 重新打包 + App 曾触发弹窗

Apple 不提供跳转到「隐私 → 蓝牙」的公开深链；插件 openPermissionSettings('bluetooth') 会打开 App 设置页并配合引导文案。

---

4. Harmony 配置

4.1 harmony-configs 要不要配？

使用 m-permission-manager 时，一般不需要在 harmony-configs/ 里重复声明权限。

鸿蒙端权限有两种配置路径：

方式	配置文件	适用场景
UTS 插件声明（推荐）	uni_modules/m-permission-manager/utssdk/app-harmony/module.json5	插件打包为鸿蒙子模块（HAR），权限对整个 App 生效
宿主工程覆盖	harmony-configs/entry/src/main/module.json5	插件未覆盖的权限、或希望在宿主侧集中管理

鸿蒙官方规则：已在子模块中声明的权限，主工程无需重复添加，权限在整个应用中生效。
m-permission-manager 作为 UTS 插件，其 module.json5 会在编译时拷贝为插件子模块的 src/main/module.json5，因此默认情况下宿主不必再配。

当前项目的 harmony-configs/ 主要用于：

文件	用途
AppScope/app.json5	包名、版本、图标（HX 4.31+ 也可在 manifest.json → app-harmony 图形界面配置）
build-profile.json5	签名证书（.cer / .p12 / .p7b）
entry/build-profile.json5	release 混淆等构建选项
entry/obfuscation-rules.txt	混淆规则

若要在 harmony-configs 中配置权限（可选，非必须）：

1. 先运行一次鸿蒙编译，从 unpackage/dist/dev/app-harmony/entry/src/main/module.json5 复制完整文件到 harmony-configs/entry/src/main/module.json5
2. 仅修改 module.requestPermissions 节点，其他节点不要删（uni-app 是文件级覆盖，不是 JSON 节点合并）
3. 不要与插件已声明的权限重复

集成 m-permission-manager 时，优先改插件内的 module.json5 / module.full.json5，而不是 harmony-configs。

4.2 插件内置文件

目录：uni_modules/m-permission-manager/utssdk/app-harmony/

文件	权限数量	APL 等级	用途
module.json5	5 项	normal	默认生效，调试证书可直接安装
module.normal.json5	5 项	normal	与 module.json5 相同，备份参考
module.full.json5	9 项	normal + system_basic	含相册 / 通讯录，需 ACL 签名

权限说明文案：resources/base/element/string.json

4.3 默认 module.json5（5 项 normal）

插件 Key	ohos.permission	说明
camera	CAMERA
microphone	MICROPHONE
location	LOCATION
coarseLocation	APPROXIMATELY_LOCATION
bluetooth	ACCESS_BLUETOOTH

4.4 module.full.json5 额外 4 项（system_basic，需 ACL）

插件 Key	ohos.permission	APL	说明
photoLibrary / readStorage	READ_IMAGEVIDEO	system_basic	需 ACL
storage	WRITE_IMAGEVIDEO	system_basic	需 ACL
contacts	READ_CONTACTS	system_basic	需 ACL
writeContacts	WRITE_CONTACTS	system_basic	需 ACL

4.5 如何切换 full 版本

1. 将 module.full.json5 的内容覆盖 module.json5
2. 在 AppGallery Connect 配置 ACL 白名单
3. 使用正式 Profile 重新签名打包
4. 重新制作自定义基座或云打包

4.6 未声明 ACL 权限时的插件行为

场景	检查 status	申请结果
相册 / 通讯录等未在 module.json5 声明	restricted	9020003，附未声明说明
系统设置	无对应开关	引导使用 uni.chooseImage 或切换 full 版本

4.7 安装报 9568289

说明 module.json5 中含有未签名的 system_basic 权限。请确认使用默认 5 项 normal 版本；若已合并 full 版本，需先完成 ACL 与 Profile 签名。

4.8 鸿蒙不支持的功能

以下插件 Key 在鸿蒙返回 unsupported：phone、phoneState、sms、readSms、receiveSms、overlay、writeSettings。

---

5. 配置示例（按业务场景）

5.1 仅需相机 + 麦克风

Android manifest：

"permissions": [
  "<uses-permission android:name=\"android.permission.CAMERA\"/>",
  "<uses-permission android:name=\"android.permission.RECORD_AUDIO\"/>"
]

iOS privacyDescription：

"privacyDescription": {
  "NSCameraUsageDescription": "需要使用相机",
  "NSMicrophoneUsageDescription": "需要使用麦克风"
}

Harmony：默认 module.json5 已包含，无需修改。

5.2 需要蓝牙

Android manifest 增加：

"<uses-permission android:name=\"android.permission.BLUETOOTH_CONNECT\"/>",
"<uses-permission android:name=\"android.permission.BLUETOOTH_SCAN\"/>"

iOS privacyDescription 增加：

"NSBluetoothAlwaysUsageDescription": "需要使用蓝牙连接周边设备"

Harmony：默认 module.json5 已包含 ACCESS_BLUETOOTH。

5.3 需要相册读写（Harmony 完整权限）

1. 用 module.full.json5 覆盖 module.json5
2. 配置 ACL 签名
3. Android 增加 READ_MEDIA_IMAGES / READ_MEDIA_VIDEO
4. iOS 增加 NSPhotoLibraryUsageDescription

若仅需选图不上传，推荐使用 uni.chooseImage，三端均无需媒体读写权限。

---

6. 配置后必做

1. 重新制作自定义基座或云打包（UTS 插件 + manifest 变更均须重新打包）
2. iOS 修改 privacyDescription 后建议删除旧 App 重装，以重新触发授权弹窗
3. Harmony 切换 module.json5 后需重新签名安装

---

7. 相关文档

• readme.md — API 与权限 Key 对照表
• 使用规范.md — 集成流程与审核注意事项
• 发布指南.md — 插件市场发布填写参考