HarmonyOS 发布工程实践 01|权限声明、授权时机与隐私信息核查【鸿蒙心迹】
项目进入提审前一周,最容易出现的一种对话是这样的:开发说“功能没问题”,测试说“功能是没问题,但这几个授权弹窗为什么一打开首页就出现”,负责上架的同事又追问:“应用市场里的隐私标签到底按哪个版本填写?”
大家说的都没错,只是关注点不在同一层。代码里声明了权限,不代表用户已经授权;系统弹出授权框,不代表权限用途解释完整;填写了隐私政策,也不等于应用市场的隐私标签与真实数据行为一致。我们把这些信息分别交给不同同事处理,最后往往靠一张聊天截图完成交接。只要功能改过一次,那张截图就过期了。
这次用一个小工具 “发布核查台” 把流程重新串起来。它不替代官方审核,也不负责给应用“盖章通过”,只做开发阶段能落地的三件事:收集工程内的权限声明、记录用户触发的授权场景、整理待与隐私政策和开发者中心核对的检查项。目标不是让文档变厚,而是让每个结论有地方追溯。

一、先统一一张清单,否则所有人都在检查不同东西
我先把提审前的资料分成四份:工程声明、运行时行为、数据使用说明、平台录入项。它们互相有关,但不能简单互相替代。
工程声明主要看 module.json5 里的 requestPermissions。用户授权要看实际在哪个按钮或功能动作后请求系统权限。数据使用说明要梳理数据是什么、为什么处理、是否上传、保存多久、用户怎么控制。平台录入项则包括开发者中心的应用隐私说明、隐私标签和隐私政策地址。
把这四份放在一起,审核链路就变成:
功能清单与数据流
↓
module.json5 权限声明
↓
用户触发时的授权行为
↓
隐私政策、应用内说明和平台隐私标签对齐
↓
提审前人工复核 + 自动静态检查
这里有一个容易误会的地方:隐私标签不是在工程目录里随便新建一个 privacy.json 就算提交。对于需要录入隐私标签的 HarmonyOS 应用,实际操作应按 HarmonyOS 开发者中心版本上架页面的字段完成,同时核对应用内的数据处理情况。后面文章中的清单 JSON 是“发布核查台”自己保存的工作台数据,不是平台认可的官方隐私标签文件格式。

二、module.json5 里只声明确实要用的权限
先不要急着把系统权限列表复制进项目。对一个普通的“发布核查台”,如果只做本地清单查看,通常根本不需要位置、相机或麦克风权限。为了讲清楚运行时授权,这里给 Demo 额外准备了一个**用户主动点击“检查附近地点”**的可选入口;只有这个入口实际接入位置能力时,才保留对应权限。
在 entry/src/main/module.json5 的 module.requestPermissions 中声明:
{
"module": {
"name": "entry",
"type": "entry",
"mainElement": "EntryAbility",
"requestPermissions": [
{ "name": "ohos.permission.INTERNET" },
{
"name": "ohos.permission.LOCATION",
"reason": "$string:permission_location_reason",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
}
]
}
}
INTERNET 是网络能力声明,LOCATION 则属于需要用户授权的权限。官方权限声明文档要求:user_grant 权限必须有 reason,并用字符串资源说明具体用途;usedScene 用于描述使用组件与调用时机。真实项目还应核查当前 SDK 的权限等级与受限开放条件,不要仅凭权限名称判断是否能申请。
在 entry/src/main/resources/base/element/string.json 放入对应文字:
{
"string": [
{
"name": "permission_location_reason",
"value": "用于您主动查看附近地点时获取当前位置。"
}
]
}
这句话比“需要位置权限以优化体验”有效得多:用户知道做什么,也知道什么时候会触发。如果产品后来删除了附近地点功能,应连带删除权限声明、文案、相关调用及隐私说明;不要想着“以后也许用得上,先留着”。

先做权限减法,往往比再加一条声明更重要
我会要求团队把所有权限先放进一张“功能—权限”映射表,再考虑是否保留。这张表里,功能必须是真正存在、用户能找到的操作,不能是“以后可能需要”。例如网络更新公告只需要正常联网能力,就没有理由附带相机权限;把本地检查结果分享给其他应用,也应优先考虑系统提供的文件选择、分享等免授权或较少授权方案,而不是直接申请宽泛的存储权限。
还有一个重要原则:权限范围应该随功能最小化。位置能力是否只需粗略位置,媒体访问是否可以采用系统 Picker,后台能力是否必须长期保留,都要先看官方推荐路径。功能能用更小的权限范围完成,先选择小的方案。审核风险下降是一方面,更重要的是用户真正获得了可控体验。
多模块项目还要注意归属关系:一个功能模块增加了敏感能力,主工程打包后也可能带上相关声明。因此每次引入新模块或者三方 SDK,都要重新执行一次全工程检查。团队经常在功能评审时关注“调用了什么 API”,却忘了“最终软件包携带了什么声明”,这正是上架前容易产生差异的地方。
三、授权框应该出现于用户知道为什么需要它的那个瞬间
工程声明完成只是第一步。运行时授权尤其容易出问题:页面一打开就申请位置,用户还没点任何按钮,自然不知道应用为什么要这个权限。更合理的是把授权绑定到操作上。
以下代码展示一个最小路径。它需要从组件或 UIAbility 中取得有效的 UIAbilityContext,并在用户点击“检查附近地点”后调用:
import { abilityAccessCtrl, Permissions, common } from '@kit.AbilityKit'
async function requestLocationForAction(
context: common.UIAbilityContext
): Promise<boolean> {
const manager = abilityAccessCtrl.createAtManager()
const permissions: Permissions[] = ['ohos.permission.LOCATION']
const result = await manager.requestPermissionsFromUser(
context,
permissions
)
return result.authResults.length > 0 &&
result.authResults.every((status) => status === 0)
}
点击处理器里再决定下一步:
private async openNearby(): Promise<void> {
const context = getContext(this) as common.UIAbilityContext
const granted = await requestLocationForAction(context)
if (!granted) {
this.notice = '未获得位置权限,仍可继续查看普通检查清单。'
return
}
// 得到授权后再调用与附近地点相关的业务能力。
}
上面用 0 对照授权结果的示例,工程里也可以换成 SDK 提供的 GrantStatus 枚举。真正重要的不是这行比较,而是不要缓存“用户曾经授权过”的结论。用户随时可能在设置里撤销权限,每次访问受保护能力前都要重新核验。若用户拒绝授权,不要循环弹窗;给出清楚解释,保留不依赖权限的基本使用路径。

一个具体问题:页面日志里能看到授权成功,就算自检完了吗
不算。授权成功只说明在那次操作、那个设备状态下拿到了系统授权。它不能说明权限申请理由与 UI 操作一致,也不能证明功能关闭后没有继续访问位置。我们至少还要检查三个时间点:点击之前是否没有无必要访问;点击之后是否只执行目标操作;离开该功能以后是否不再无故收集相关信息。
如果页面涉及多个权限,授权结果也不应被压成一个笼统的布尔值后就丢掉。应记录每个权限项的状态,用于向用户解释具体缺少哪种能力。对于未授权状态,提示文案应说清楚“功能受限”而不是恐吓用户“应用无法正常使用”。例如“附近地点暂时不可用,您仍可查看已保存的检查结果”,比一条泛泛的“权限拒绝,操作失败”更友好,也更符合最小化原则。
注意日志边界。用来排查权限时机的日志记录事件类别、触发页面和权限名称即可,不必把真实位置、设备标识或个人内容写入公开调试日志。权限合规做得越细,越应该防止核查工具本身变成敏感信息的额外采集源。
四、隐私说明不是写一句“我们重视您的隐私”
在开发者中心提交应用时,隐私相关内容至少有三条不同工作线:应用隐私说明、隐私政策、隐私标签。这三个词长得相似,但作用不同。
应用隐私说明通常与软件包检测出的敏感隐私权限和受限开放权限有关。对于敏感隐私权限,要逐项解释用途;如果涉及受限开放权限,平台还可能要求使用场景视频和对应的发布 Profile 权限。隐私政策是面向用户的公开说明,应在应用内和开发者平台提供可便捷访问的入口。隐私标签则从业务场景、数据项、处理目的等角度告诉用户应用如何使用个人信息。有权限不一定收集并上传个人信息,没申请某种系统权限也不代表不会处理个人信息,所以不能简单用权限清单自动生成整份隐私标签。
我会让产品、开发和测试各填一列:
| 核查字段 | 需要回答的问题 | 对应核验证据 |
|---|---|---|
| 功能场景 | 什么动作触发了数据处理? | 页面入口、交互说明 |
| 权限名称 | 是否必须声明?属于哪种权限级别? | module.json5、权限列表 |
| 数据项 | 访问或收集哪些信息? | 接口文档、运行行为 |
| 用途 | 信息用于完成哪个明确功能? | 权限 reason、隐私政策 |
| 存储与传输 | 仅设备内使用还是上传?保存多久? | 数据流、服务端说明 |
| 用户选择 | 拒绝后能否继续?怎样撤销? | 授权与设置流程 |
| 平台填写 | 隐私说明、隐私标签是否一致? | 开发者中心版本记录 |
官方平台有“无个人信息收集”的选项,但是否选择“否”,必须以整个应用和所集成第三方组件的真实行为为准。不能为了少填项目而勾“否”,也不能把所有可能的数据项一股脑勾上。

平台信息为什么要与版本绑定
同一个应用在不同版本中,采集和处理的数据并不一定相同。假设 1.1 版本没有附近地点功能,1.2 才增加,两个版本的权限声明和隐私相关说明就需要分别核对。团队若长期维护一份不带版本的“隐私标签截图”,很容易在升级提交时继续沿用旧信息。
因此“发布核查台”中每条隐私核对记录都应该带上 bundleName、versionCode、配置文件路径和提交号。这样即便同一个权限在不同版本里的使用时机改变,复核人也能指出差异。对于服务端新增的数据用途,也应同步到数据使用清单;不能因为客户端代码没动,就认为隐私政策不需要更新。
这不是做复杂的合规平台。最初甚至可以用一个 CSV 配合问题单管理。但“版本”这一列一定要有,否则存下来的证据越多,后面反而越难追溯。
五、让自动检查做重复劳动,让人来判断业务合理性
从这里开始才轮到“发布核查台”真正发挥作用。我们给它做一个静态扫描脚本:遍历工程中的 module.json5,汇总所有模块的权限声明,标记缺少 reason 或缺少 usedScene 的情况,并输出一个供人工复核的清单。
注意:脚本不能凭权限名推断全部权限级别,更不能判断隐私政策是否合规。它只是减少漏看配置项的概率。多模块项目中,子模块也可能声明权限;只检查 entry 模块很容易遗漏。
脚本使用 Node.js 和 json5 读取配置,先安装开发依赖:
npm install --save-dev json5
scripts/audit-permissions.mjs 的核心部分:
import fs from 'node:fs'
import path from 'node:path'
import JSON5 from 'json5'
const ignored = new Set(['node_modules', 'oh_modules',
'build', '.git', '.hvigor'])
const files = []
function walk(dir) {
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
const full = path.join(dir, entry.name)
if (entry.isDirectory() && !ignored.has(entry.name)) walk(full)
else if (entry.isFile() && entry.name === 'module.json5') files.push(full)
}
}
walk(process.cwd())
const rows = []
for (const file of files) {
const moduleConfig = JSON5.parse(fs.readFileSync(file, 'utf8')).module ?? {}
for (const perm of moduleConfig.requestPermissions ?? []) {
rows.push({ module: moduleConfig.name, file,
permission: perm.name,
hasReason: Boolean(perm.reason),
hasScene: Boolean(perm.usedScene?.when || perm.usedScene?.abilities),
review: '请人工确认权限级别、业务必要性与隐私说明一致性' })
}
}
fs.writeFileSync('permission-audit.json', JSON.stringify(rows, null, 2))
console.log(`检查 ${files.length} 个模块,汇总 ${rows.length} 条权限声明`)
这份脚本有意不直接输出“合规/不合规”。例如 INTERNET 不需要像敏感 user_grant 权限那样写 reason,静态脚本只记录字段存在性,之后按权限等级核对。更进一步的版本可以维护一份与当前 SDK 权限列表同步的人工审阅清单,把受限开放权限列为必须人工确认的高优先级问题。

自动扫描再往前走一步:别只输出一个总数
有些脚本只会打印“检查到 5 条权限声明”,然后就结束了。这个结果对实际整改帮助不大。更值得输出的是按模块归属分组的清单,包括声明文件、权限名称、reason 资源引用、usedScene 中的调用时机、业务功能负责人以及待验证项目。这样一个模块引入新依赖时,团队能立即看到声明数量和来源发生了什么变化。
我会给扫描结果增加一份 diff:与上次提交对比,新增了哪些权限、删除了哪些权限、修改了哪些 reason 引用。尤其是“新增权限”,最好触发一条明确的人工复核任务,而不是静默地把它合并到报告里。由于这些规则依赖 SDK 权限分级和官方审核要求,脚本不应该自行凭字符串判断权限“合法”,也不应该自动勾选开发者中心的隐私数据项。
最小可行做法是:CI 归档本次报告,人工复核后记录结论。把工具放在帮助开发者发现遗漏的位置,而不是让一个 PASS 字样假装替代了上架审核。
六、在页面里做一张真正能交接的检查卡片
“发布核查台”首页不需要花哨。左侧列出四块检查项:工程配置、运行时授权、隐私说明、平台信息;右侧展示每一项的状态和负责人。状态我只保留三个:待核、需整改、已复核。这里没有“平台审核通过”按钮,因为内部复核和官方最终审核是两回事。
每一条检查卡要能回答:谁发现的问题,什么时候验证的,具体哪个文件或页面需要处理,整改以后由谁复核。尤其是权限类问题,最好保留“触发前”和“用户拒绝后”的界面记录,方便上架同事了解真实场景。
除了自动输出的 permission-audit.json,工作台可以再维护一份人工清单:
{
"issueId": "PRIV-006",
"topic": "位置授权触发时机",
"location": "entry/src/main/ets/pages/Index.ets",
"status": "needs_review",
"owner": "客户端开发",
"evidence": "用户点击附近地点后触发授权",
"nextAction": "确认拒绝授权后的普通清单仍可使用"
}
这样提交前的讨论会从“这个做了吗”变成“PRIV-006 的复核证据在哪里”。沟通方式变了,返工成本也会下降。

权限、个人信息与业务能力,最好用同一套词说明
产品文案里写“附近地点”,工程里叫 LOCATION,隐私政策写“定位服务”,平台标签里又可能按照数据类型分类。如果这些名称相互对应不上,审核人员就只能来回追问。我的处理办法很简单:给每个实际功能一个稳定的业务 ID,再把代码入口、系统权限、数据项、文案和平台填报位置都映射到它。
例如 NEARBY_PLACE 关联到“检查附近地点”按钮,使用位置权限,获取位置只为了展示用户主动请求的周边结果。若后面产品要求把搜索记录长期上传保存,那就不是同一套“仅用于附近查询”的说明能够覆盖的范围,必须重新审查数据流和隐私文字。
这件事听上去像文档管理,实际是在降低后续维护风险。相比把所有材料复制成多份表格,稳定的业务场景标识 + 可追溯证据更有价值。
七、真正要验的不是全绿,而是四种拒绝与变化
很多权限问题只有在非理想流程里才会露出来。提审前我会安排这样一轮回归:首次进入应用不主动申请敏感权限;用户打开可选功能后才出现授权;拒绝授权时页面保留基本功能;从系统设置撤销授权以后再次执行操作,应用能重新校验并给出合理反馈。
隐私信息也要做一次反向检查。先把实际使用的数据项列出来,再逐项找到隐私政策和平台标签中的对应说明;如果找不到,就不能因为“已经填过”而跳过。接入第三方组件后,供应方的数据处理行为同样要纳入核验。
最后我会单独过一遍官方受限开放权限清单。若某项权限需要审核批准,应用功能、Profile 中申请的权限和上架场景必须匹配,不能依赖 Debug 阶段“能运行”来推断上线没有问题。

交接清单里一定要写清“不由本工具判断”的部分
我会在 README 里明确列出“发布核查台”不替代的工作:第三方 SDK 数据流核验、隐私政策法律审阅、受限权限审批、平台审核结论。这样的边界不是推卸责任,而是避免团队拿着内部工具的通过截图就直接认定万事大吉。
如果内部检查项已经全部复核,平台却仍返回修改要求,正确的做法是把要求追加成一条新的问题单,补充责任人与证据,然后在下一次提交时复查;不要因为“我们工具显示已通过”就怀疑平台一定出错。真正能降低返工的,不是一次过关率的承诺,而是每次修改都知道原因,并能验证问题是否确实关闭。
八、把“审核工作”提前到开发阶段
这篇没有试图写一份万能审核规则。审核要求会更新,不同设备、应用类别和权限级别也有不同要求。我更想留下的是一条工程习惯:每新增一个权限,同时补理由、触发场景和隐私核对项;每删除一个功能,同时检查它的权限有没有残留。
“发布核查台”第一版最终只做出了几件朴素的东西:多模块权限汇总、使用场景记录、隐私材料对照表、问题单、复核状态和提审前清单。看起来不如新功能显眼,但当团队真的准备发布时,这些东西比临时翻聊天记录有用得多。
下一篇要解决另一个经常在最后一天才冒出来的问题:权限与隐私整理好了,Release 包、签名和 AGC 上传流程能不能一次走通。
官方资料与核对入口
更多推荐


所有评论(0)