HarmonyOS 权限申请自检:代码需要、配置声明、隐私说明要如何对得上【鸿蒙心迹】

👋 你好,欢迎来到我的博客!我是【菜鸟学鸿蒙】
我是一名在路上的移动端开发者,正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来,也为了和更多同路人互相启发,我决定把探索 HarmonyOS 的过程都记录在这里。
🛠️ 主要方向:ArkTS 语言基础、HarmonyOS 原生应用(Stage 模型、UIAbility/ServiceAbility)、分布式能力与软总线、元服务/卡片、应用签名与上架、性能与内存优化、项目实战,以及 Android → 鸿蒙的迁移踩坑与复盘。
🧭 内容节奏:从基础到实战——小示例拆解框架认知、专项优化手记、实战项目拆包、面试题思考与复盘,让每篇都有可落地的代码与方法论。
💡 我相信:写作是把知识内化的过程,分享是让生态更繁荣的方式。
如果你也想拥抱鸿蒙、热爱成长,欢迎关注我,一起交流进步!🚀
前言
应用上架被拒,很多时候问题出在权限上——但不是权限本身写错了,而是三个地方没对齐:代码里实际用到的权限、module.json5 里声明的权限、隐私政策里说明的权限。这三个地方只要有一个和另外两个脱节,轻则审核打回,重则上线后被用户举报隐私合规问题。
这篇文章以一个包含相机、位置、麦克风三类权限的典型应用为例,把权限自检的完整流程梳理一遍。
一、权限问题为什么容易拖到审核阶段才发现
权限问题有一个共同特征:它在本地开发阶段几乎不影响运行。
module.json5 里多声明几个权限,应用照样安装和运行。某个业务模块被砍掉了,但对应的权限声明没人删,编译不报错,测试也发现不了。等到提审,华为的审核工具和人工核查会把你声明的每一条权限和实际业务对应起来——这时候才发现,有三个权限在代码里根本找不到调用入口。
还有另一个方向的问题:代码里调用了某个需要权限的 API,但忘了在 module.json5 里声明,真机运行时直接抛 permission denied 异常。这类问题在模拟器上不容易复现,因为模拟器对权限检查有时不够严格。
两种情况加在一起,导致权限问题基本是"开发时埋雷,审核时踩雷"。
二、先列出项目实际声明的权限
自检的第一步不是去看代码,而是先打开 module.json5,把 requestPermissions 字段下的所有权限完整抄下来,形成一张表。
以一个包含拍照、录音、获取位置功能的应用为例,module.json5 可能长这样:
{
"module": {
"requestPermissions": [
{
"name": "ohos.permission.CAMERA",
"reason": "$string:reason_camera",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
},
{
"name": "ohos.permission.MICROPHONE",
"reason": "$string:reason_microphone",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
},
{
"name": "ohos.permission.APPROXIMATELY_LOCATION",
"reason": "$string:reason_location",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
},
{
"name": "ohos.permission.LOCATION",
"reason": "$string:reason_location",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "always"
}
}
]
}
}
把这四条权限先记录在表格里,作为后续比对的基准。
三、找到每条权限对应的业务功能
有了声明清单之后,第二步是在代码里找每条权限的实际调用位置。
HarmonyOS 权限分为 system_grant 和 user_grant 两类。user_grant 类权限在运行时需要通过 abilityAccessCtrl 模块向用户申请,所以全局搜索 requestPermissionsFromUser 的调用位置,是定位权限使用点最快的方式。
同时搜索各权限对应的系统能力调用,例如:
ohos.permission.CAMERA→ 通常对应相机 API 或媒体录制相关调用ohos.permission.MICROPHONE→ 通常对应音频录制ohos.permission.LOCATION/ohos.permission.APPROXIMATELY_LOCATION→ 对应位置服务
整理完成后,给表格补上第二列"对应功能"。如果某条权限找不到对应的业务代码,这一栏就填"未找到调用",这就是下一步要处理的情况。
四、删除已经不再使用的权限
假设排查后发现 ohos.permission.MICROPHONE 对应的录音功能已经在上个版本被砍掉,代码里不再有任何录音相关调用,这条权限就必须从 module.json5 里删掉。
按照华为应用市场的审核要求,声明了但无对应业务使用的权限会被认定为"超出必要范围申请权限",属于合规问题。官方在应用权限管理概述中明确指出,应用应遵循最小权限原则,只申请完成业务功能所必需的权限。
删除权限时注意同步检查两个地方:
module.json5中的requestPermissions条目- 代码里
requestPermissionsFromUser调用传入的权限数组,确保没有残留
五、检查运行时申请逻辑
声明了权限还不够,user_grant 类权限必须在运行时通过 abilityAccessCtrl 向用户申请,且申请时机要和 usedScene.when 字段保持一致。
按照官方文档,标准的运行时权限申请流程分三步:先检查当前权限状态,再决定是否发起申请,最后处理用户的响应结果。
import { abilityAccessCtrl, bundleManager, common, Permissions } from '@kit.AbilityKit';
// 在 UIAbility 的 onWindowStageCreate 或具体功能入口调用
async function checkAndRequestCameraPermission(context: common.UIAbilityContext): Promise<boolean> {
const permission: Permissions = 'ohos.permission.CAMERA';
const atManager = abilityAccessCtrl.createAtManager();
// 第一步:获取当前应用的 tokenId
let tokenId: number = 0;
try {
const bundleInfo = await bundleManager.getBundleInfoForSelf(
bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION
);
tokenId = bundleInfo.appInfo.accessTokenId;
} catch (err) {
console.error('getBundleInfoForSelf failed:', JSON.stringify(err));
return false;
}
// 第二步:检查权限状态
let grantStatus: abilityAccessCtrl.GrantStatus;
try {
grantStatus = await atManager.checkAccessToken(tokenId, permission);
} catch (err) {
console.error('checkAccessToken failed:', JSON.stringify(err));
return false;
}
if (grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
// 已授权,直接使用
return true;
}
// 第三步:发起申请
try {
const result = await atManager.requestPermissionsFromUser(context, [permission]);
if (result.authResults[0] === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
return true;
} else {
// 用户拒绝,进入降级处理逻辑
return false;
}
} catch (err) {
console.error('requestPermissionsFromUser failed:', JSON.stringify(err));
return false;
}
}
这段代码有几个地方值得单独注意:
checkAccessToken 不能省略。 直接每次都调 requestPermissionsFromUser 在权限已授权时也能正常返回,但官方推荐先检查再申请,避免不必要地打扰用户。
context 必须是 UIAbility 或 UIExtensionAbility 的 Context。 如果传入的是 ApplicationContext,requestPermissionsFromUser 无法弹出授权对话框,会直接报错。这是一个在封装工具类时非常容易踩的坑。
result.authResults[0] 对应第一个权限的授权结果。 如果一次申请多个权限,authResults 数组的顺序和 permissions 数组的顺序一一对应,不要混用索引。
六、对照隐私政策
权限和隐私政策的对齐,是开发者最容易忽视的一关。
华为应用市场审核时,会核查隐私政策中是否明确说明了以下内容:
- 收集哪些数据(如位置信息、录音数据、相机图像)
- 数据用途(如用于个性化推荐、用于内容创作)
- 是否与第三方共享
对照前面整理的权限清单,每一条权限对应的数据采集行为,都必须在隐私政策里有对应描述。常见的遗漏情况是:
- 代码里新增了位置功能,但隐私政策版本还是半年前的,没有位置数据说明
- 接入了第三方 SDK,SDK 内部会申请某些权限采集数据,但隐私政策里没有说明该 SDK 的数据处理行为
位置权限有一个特别需要注意的地方:ohos.permission.LOCATION(精确位置)和 ohos.permission.APPROXIMATELY_LOCATION(模糊位置)在 HarmonyOS 权限体系中是两个独立的权限。如果业务只需要城市级别的定位,声明精确位置权限就属于超范围申请。隐私政策里对"位置精度"的描述,也需要和实际申请的权限类型匹配。
七、权限被拒绝后的用户体验
权限被用户拒绝有两种情况:
- 用户本次拒绝,但没有选择"不再询问"——下次进入相关功能时还可以再次发起申请
- 用户选择了"不再询问"并拒绝——此后
requestPermissionsFromUser不会再弹出授权弹窗
对于第二种情况,官方推荐的处理方式是引导用户主动前往系统设置开启权限。从 API 12 起,AtManager 提供了 requestPermissionOnSetting 接口,可以直接引导用户进入对应权限的设置页面。在 API 12 以下的版本中,可以通过 startAbility 的方式跳转到系统设置。
这里容易出现的体验问题是:用户拒绝了某个非核心权限之后,应用直接崩溃或卡住。正确做法是对权限拒绝场景做降级处理——如果拒绝的是非核心功能权限,应该允许用户继续使用其他功能,同时在相关功能入口给出友好提示和引导。
如果拒绝的是核心功能权限(比如相机类应用的相机权限),也应该通过 Dialog 或 Toast 说明原因,并提供跳转设置的入口,而不是直接 return 什么都不做。
// 权限被永久拒绝后,引导用户前往设置(API 12+)
import { abilityAccessCtrl } from '@kit.AbilityKit';
async function guideToSettings(context: common.UIAbilityContext): Promise<void> {
const atManager = abilityAccessCtrl.createAtManager();
try {
// requestPermissionOnSetting 会拉起系统权限设置界面
await atManager.requestPermissionOnSetting(context, ['ohos.permission.CAMERA']);
} catch (err) {
console.error('requestPermissionOnSetting failed:', JSON.stringify(err));
}
}
八、发布前权限自检表
把前面几步整理成一张可复用的清单,每次发版前过一遍:
| 检查项 | 说明 | 状态 |
|---|---|---|
| module.json5 中每条权限均有对应业务代码 | 无对应代码的权限必须删除 | □ |
| 代码中每处权限调用在 module.json5 中均已声明 | 防止运行时 permission denied | □ |
| user_grant 权限均有运行时申请逻辑 | system_grant 权限无需此项 | □ |
| reason 字段使用 $string 资源引用,内容清晰准确 | 不能直接写中文字符串 | □ |
| usedScene.when 与实际申请时机一致 | inuse 或 always | □ |
| 精确位置与模糊位置权限按实际需要选择 | 不超范围申请 | □ |
| 隐私政策中覆盖所有权限对应的数据采集说明 | 包含第三方 SDK 采集行为 | □ |
| 权限被拒绝后有合理的降级或引导处理 | 不影响无关功能使用 | □ |
| 多 Module 项目中各 Module 权限独立检查 | HAP/HSP 分别核查 | □ |
开发经验总结
-
权限声明和业务代码的脱节,是审核被拒最常见但最容易预防的原因。 建议在砍功能、删模块的时候,把权限清单的维护列为标准步骤,而不是等到提审前再统一检查。
-
reason字段必须用$string资源引用。 如果直接写中文字符串,编译不报错,但在 DevEco Studio 的 Lint 检查中会有警告,审核阶段也可能被判定为配置不规范。 -
requestPermissionsFromUser的 context 来源需要严格确认。 封装权限工具类时,context 通常需要从 UIAbility 向下传递,不能直接用getContext()获取 ApplicationContext 来替代。 -
位置权限申请建议从模糊位置入手。
ohos.permission.APPROXIMATELY_LOCATION相当于精确位置申请的前置权限,实际上申请精确位置时需要同时声明这两个权限,但如果业务只需要模糊位置,只申请APPROXIMATELY_LOCATION即可,避免过度申请。 -
多 HAP 或包含 HSP 的项目,每个 Module 的
module.json5需要独立检查。 权限是 Module 级别声明的,主 Module 声明的权限不会自动覆盖其他 Module。
📝 写在最后
如果你觉得这篇文章对你有帮助,或者有任何想法、建议,欢迎在评论区留言交流!你的每一个点赞 👍、收藏 ⭐、关注 ❤️,都是我持续更新的最大动力!
我是一个在代码世界里不断摸索的小码农,愿我们都能在成长的路上越走越远,越学越强!
感谢你的阅读,我们下篇文章再见~👋
✍️ 作者:菜鸟不学编程
🧵 本文原创,转载请注明出处。
更多推荐




所有评论(0)