HarmonyOS 权限不能只看“有没有声明“:先把授权类型分清楚【鸿蒙心迹】

你是不是也在想——“鸿蒙这么火,我能不能学会?”
答案是:当然可以!
这个专栏专为零基础小白设计,不需要编程基础,也不需要懂原理、背术语。我们会用最通俗易懂的语言、最贴近生活的案例,手把手带你从安装开发工具开始,一步步学会开发自己的鸿蒙应用。
不管你是学生、上班族、打算转行,还是单纯对技术感兴趣,只要你愿意花一点时间,就能在这里搞懂鸿蒙开发,并做出属于自己的App!
📌 关注本专栏《零基础学鸿蒙开发》,一起变强!
每一节内容我都会持续更新,配图+代码+解释全都有,欢迎点个关注,不走丢,我是小白酷爱学习,我们一起上路 🚀
全文目录:
前言
声明了权限,不代表拿到了权限。
这个误区在实际开发中很常见:module.json5 里加上了 requestPermissions,代码跑起来却还是报 Permission denied;或者权限弹窗该出现的时候没出现,不该出现的时候一直弹。根本原因通常不是写错了什么,而是没搞清楚 HarmonyOS 权限系统里,"声明"和"授权"是两件性质不同的事。
一、为什么光"声明"不够
很多开发者把 HarmonyOS 权限配置理解成一件事:往 module.json5 里写 requestPermissions。
这种理解只对了一半。
requestPermissions 的作用是向系统登记这个应用打算使用某项权限,相当于一份意向声明,系统在安装或运行时会根据这份声明去做后续处理。但后续怎么处理,完全取决于这条权限本身属于哪种授权类型。
HarmonyOS 官方文档把权限按授权方式分成两个维度来看:
第一个维度:授权主体是谁
- system_grant(系统授权):系统在安装应用时自动完成授权,不需要用户操作
- user_grant(用户授权):必须在运行时主动弹窗请求,由用户决定是否授予
第二个维度:权限的开放程度
- 普通权限(normal):满足基本条件即可使用
- 受限权限(restricted):受到额外限制,普通应用在未通过审批前不能使用,需要通过 ACL(Access Control List)机制申请开放
四种情况的组合,决定了某条权限在实际运行时能不能用、如何才能用。
二、把四种情况拆开看
2.1 system_grant:声明即生效
ohos.permission.INTERNET 是一个典型例子。这条权限的授权类型是 system_grant,应用在 module.json5 里声明之后,系统会在安装时自动授予,代码中不需要再主动请求。
这类权限的特征:操作范围有限、对用户隐私影响较低,系统可以直接决策。
开发时只需要这一步:
// module.json5
{
"module": {
"requestPermissions": [
{
"name": "ohos.permission.INTERNET"
}
]
}
}
安装后即可直接使用,不需要调用任何运行时申请接口。
2.2 user_grant:声明 + 运行时请求,缺一不可
ohos.permission.CAMERA、ohos.permission.LOCATION、ohos.permission.READ_CONTACTS 等属于 user_grant。
这类权限影响到用户的隐私和敏感数据,系统不会自动授予,必须在运行时弹窗让用户确认。
只在 module.json5 里声明但不调用运行时申请接口,权限永远拿不到。
完整流程分三步:
第一步:module.json5 中声明
// module.json5
{
"module": {
"requestPermissions": [
{
"name": "ohos.permission.CAMERA",
"reason": "$string:reason_camera",
"usedScene": {
"abilities": [
"EntryAbility"
],
"when": "inuse"
}
}
]
}
}
reason 和 usedScene 对于 user_grant 权限是必填项,AGC 审核也会检查这两个字段是否配置合理。
第二步:运行时检查当前授权状态
在真正使用权限之前,先确认用户是否已经授过权:
import { abilityAccessCtrl, bundleManager, Permissions } from '@kit.AbilityKit';
async function checkPermission(permission: Permissions): Promise<boolean> {
let atManager = abilityAccessCtrl.createAtManager();
let grantStatus: abilityAccessCtrl.GrantStatus;
// 获取当前应用的 tokenID
let tokenId: number = 0;
try {
let bundleInfo = await bundleManager.getBundleInfoForSelf(
bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION
);
tokenId = bundleInfo.appInfo.accessTokenId;
} catch (err) {
return false;
}
// 检查授权状态
try {
grantStatus = await atManager.checkAccessToken(tokenId, permission);
} catch (err) {
return false;
}
return grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
}
第三步:未授权时主动请求
import { common, abilityAccessCtrl, Permissions } from '@kit.AbilityKit';
async function requestCameraPermission(context: common.UIAbilityContext): Promise<void> {
const permissions: Array<Permissions> = ['ohos.permission.CAMERA'];
let atManager = abilityAccessCtrl.createAtManager();
try {
let result = await atManager.requestPermissionsFromUser(context, permissions);
// result.authResults[0] === 0 表示用户授权成功
if (result.authResults[0] === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
// 授权成功,可以继续后续操作
} else {
// 用户拒绝,需要引导用户去设置页面手动开启
}
} catch (err) {
// 处理异常
}
}
requestPermissionsFromUser 需要传入 UIAbilityContext,这个 context 要从 UIAbility 的生命周期中获取,不能在非 UI 上下文里直接调用。
2.3 受限权限(restricted)与 ACL 机制
受限权限是 HarmonyOS 权限体系里容易被忽略的一层。
某些高敏感权限(例如涉及精确位置、通讯录写入、通话记录等),除了需要在 module.json5 里声明并通过运行时请求外,还需要应用具备相应的证书级别,即通过 AppGallery Connect 的 ACL 权限申请审批,才能在签名证书中获得对应的 ACL 授权。
如果没有通过 ACL 申请,即使声明了、也请求了,系统也不会授权。
官方文档对受限权限有明确说明:这类权限在权限定义文件中的 availableLevel 字段不是 normal,应用需要满足特定条件才能使用。
开发阶段用调试证书时,通常不会踩到这个限制;但用正式签名证书发布的应用,如果权限声明了却一直拿不到,就需要检查是否属于受限权限、是否完成了 ACL 申请。
ACL 相关配置会在应用签名证书中体现,build-profile.json5 中也需要正确配置签名信息,确保构建时使用的是携带 ACL 授权的证书。
三、一个最小验证场景
下面是一个最小化的 UIAbility 示例,展示如何在 onCreate 之后的合适时机完成权限检查和请求,结构本身比业务逻辑更重要:
import { UIAbility, abilityAccessCtrl, bundleManager, Want, AbilityConstant, Permissions, common } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
export default class EntryAbility extends UIAbility {
private windowStage: window.WindowStage | null = null;
onWindowStageCreate(windowStage: window.WindowStage): void {
this.windowStage = windowStage;
windowStage.loadContent('pages/Index');
// 在页面加载后执行权限检查,此时可以获取到正确的 context
this.checkAndRequestPermissions();
}
private async checkAndRequestPermissions(): Promise<void> {
const permission: Permissions = 'ohos.permission.CAMERA';
const atManager = abilityAccessCtrl.createAtManager();
// 先检查当前授权状态
let bundleInfo = await bundleManager.getBundleInfoForSelf(
bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION
);
let tokenId = bundleInfo.appInfo.accessTokenId;
let grantStatus = await atManager.checkAccessToken(tokenId, permission);
if (grantStatus !== abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
// 未授权时发起请求
let result = await atManager.requestPermissionsFromUser(
this.context as common.UIAbilityContext,
[permission]
);
console.info('权限请求结果:' + JSON.stringify(result.authResults));
}
}
}
这段代码的核心逻辑:先查再请求,而不是每次启动直接弹窗。对用户来说体验更自然,对开发者来说也便于根据状态分支处理。
四、几个关键点拆开说
4.1 checkAccessToken 和 requestPermissionsFromUser 不能混用职责
checkAccessToken 只负责查状态,不会触发弹窗;requestPermissionsFromUser 才会触发系统弹窗。如果把查询和请求的逻辑混在一起处理,很容易出现"权限明明没授,却没有弹窗"的情况——因为根本没调到请求接口。
4.2 用户拒绝后再次请求的行为
用户在弹窗里点了"拒绝"之后,如果应用直接再次调用 requestPermissionsFromUser,系统在某些情况下会直接返回拒绝,不再弹窗。官方建议:检测到权限被拒绝后,应引导用户去应用设置页面手动开启,而不是反复弹窗。
4.3 reason 字段不只是审核用的
reason 字段会在系统权限弹窗中向用户展示,解释申请该权限的原因。如果这里写的说明和应用实际用途差距很大,不仅影响用户的授权意愿,审核阶段也可能被打回。
4.4 when 字段的选项影响权限使用范围
usedScene.when 有两个值:inuse(仅在前台使用)和 always(前后台均可使用)。如果应用需要在后台持续获取位置,却只申请了 inuse,后台运行时权限会被系统收回。
五、容易踩坑的地方
① 把 system_grant 的权限走了 user_grant 的流程
对 ohos.permission.INTERNET 这类 system_grant 权限调用 requestPermissionsFromUser,系统不会报错,但弹窗不会出现,authResults 会直接返回已授权——因为系统安装时就给了。问题不在这里,在于开发者误以为这个弹窗就是用户授权的标准流程,后来换成 user_grant 权限时忘了处理用户拒绝分支。
② 签名证书没有携带对应的 ACL 授权
调试阶段用 debug 证书通常不受 ACL 限制,但换成发布证书后受限权限就会一直拿不到。这类问题的特征是:本地 debug 没问题,发布版本一直失败。排查时要检查签名证书的权限配置,而不是代码逻辑。
③ 在非 UIAbility context 里调用 requestPermissionsFromUser
requestPermissionsFromUser 要求传入的 context 具有展示系统弹窗的能力,在 ServiceExtensionAbility 或者工具类里直接调用通常会失败或行为异常。这个接口需要在 UIAbility 中使用。
④ 只在第一次启动时检查权限
用户可以随时在系统设置里撤销权限,应用运行期间权限状态可能发生变化。建议在每次真正使用该权限的功能之前(比如打开相机前、获取位置前),都先做一次 checkAccessToken 校验,而不是只在启动时检查一次。
六、排查权限问题的顺序
遇到 Permission denied 或权限弹窗不出现时,可以按这个顺序排查:
-
确认
module.json5里有没有声明
连声明都没有,系统会直接拒绝,不走后续流程 -
确认这条权限属于
system_grant还是user_grant
可以在 HarmonyOS 官方权限列表文档中查到每条权限的grantMode -
如果是
user_grant,确认是否调用了requestPermissionsFromUser
很多问题就出在这一步缺失 -
确认是否属于受限权限
如果权限文档中标注了受限,检查是否完成了 AGC 侧的 ACL 申请 -
确认签名证书是否携带了对应权限的 ACL 授权
特别是从 debug 切换到 release 签名之后 -
确认
requestPermissionsFromUser的 context 类型是否正确
传入的必须是UIAbilityContext -
确认
reason和usedScene字段是否正确填写
user_grant权限缺少这两个字段,弹窗可能无法正常触发
开发经验总结
-
HarmonyOS 权限系统的核心分层是:声明(
module.json5)→ 授权类型(system_grant/user_grant)→ 是否受限(普通 / ACL)。三个维度都要对,权限才能真正可用。 -
system_grant声明即生效,不需要运行时请求;user_grant声明之后还需要主动调用requestPermissionsFromUser,两步缺一不可。 -
受限权限在没有通过 ACL 审批前,无论代码怎么写,系统都不会授权,这是证书级别的限制,不是代码层面能绕过的。
-
权限状态在应用运行期间可以被用户撤销,建议在每次使用敏感功能前都检查一次当前状态,而不是只在启动时检查。
-
debug 证书和 release 证书在受限权限行为上可能表现不同,上架前务必用正式签名证书在真机上完整验证一遍权限流程。
如果你正在接入 user_grant 权限,可以重点观察一下自己的代码里有没有处理用户拒绝后的分支——这个分支缺失的情况很普遍,而且在测试阶段因为习惯点"允许",往往不容易发现。
❤️ 如果本文帮到了你…
- 请点个赞,让我知道你还在坚持阅读技术长文!
- 请收藏本文,因为你以后一定还会用上!
- 如果你在学习过程中遇到bug,请留言,我帮你踩坑!
更多推荐


所有评论(0)