OpenHarmony 预置应用配置详解/system/etc/app/ 下的 5 个 JSON在 OpenHarmony 设备上预置应用装不装、能不能卸载、有哪些特权、预授哪些权限全部由/system/etc/app/下的 5 个 JSON 决定。这篇文章讲清楚每个文件的作用、字段含义、生效时机以及实际踩过的坑。背景预置应用机制是怎么跑起来的预置相关文件分两处/system/app/ 预置应用的 HAP 安装包每个应用一个目录 └── com.ohos.camera/ └── com.ohos.camera.hap /system/etc/app/ BMS 读取的 5 个配置 JSON ├── install_list.json ├── install_list_capability.json ├── install_list_permissions.json ├── default_app.json └── uninstall_list.jsonBMS包管理服务开机扫描的大致流程扫描/system/app/等预置目录下的 HAP对照install_list.json安装其中尚未安装的应用在安装这一刻去install_list_capability.json应用特权能力、去install_list_permissions.json完成权限预授予按uninstall_list.json把指定应用置为已卸载态。流程里最关键的一点特权与预授权只在应用安装那一刻生效。应用已经装好了再改 JSON什么都不会发生——这是后面反复出现的坑也是改完必须重装的根本原因。一览文件作用更新后如何生效install_list.json哪些 HAP 作为预置应用安装、可否卸载对未安装应用重启即可install_list_capability.json特权能力特权扩展、常驻、隐藏图标等需重装对应应用install_list_permissions.json权限预授予ACL 授权需重装对应应用default_app.json默认应用绑定通常为空无影响uninstall_list.json预置但默认卸载 / 可恢复的应用重启即可1. install_list.json —— 预置应用安装清单{install_list:[{app_dir:/system/app/com.ohos.camera,removable:false},{app_dir:/system/app/com.ohos.wallpaper,removable:true}]}字段说明app_dirHAP 所在目录设备上的绝对路径。目录必须真实存在且其中有 HAP否则该条目安装失败开机日志里能看到 BMS 扫描报错。removabletrue用户可卸载卸载后可恢复false系统级应用不可卸载。只控制能否卸载与权限、特权无关。新增一个预置应用的完整步骤# 1. 重挂载 system 分区为可写hdc shellmount -o remount,rw /# 2. 推送 HAPhdcfilesend MyApp.hap /system/app/com.example.myapp/com.example.myapp.hap# 3. 修改 /system/etc/app/install_list.json加入条目后推回或设备上直接改# 4. 重启BMS 扫描安装hdc shellreboot注意这种方式只对尚未安装的应用生效应用此前装过的话BMS 扫描时会跳过改动不会落到已装应用身上。2. install_list_capability.json —— 特权能力配置有些能力应用无法通过module.json5申请只能由系统侧预置授予就配置在这里{bundleName:com.ohos.launcher,app_signature:[0F1E2D3C4B5A6978...],allowAppUsePrivilegeExtension:true,allowAppDesktopIconHide:true}2.1 字段说明常用字段字段含义app_signature签名证书指纹SHA-256 大写十六进制、无冒号可配多个对应不同签名环境allowAppUsePrivilegeExtension允许使用 service / push 等特权扩展类型allowAppDesktopIconHide允许隐藏桌面图标无界面的后台/对话框类应用用allowCommonEvent允许静态订阅指定公共事件如usual.event.SMS_RECEIVE_COMPLETED、usual.event.USER_ADDEDsingleton多用户下仅单实例keepAlive常驻保活associatedWakeUp允许被关联唤醒allowAppRunWhenDeviceFirstLocked首次锁屏后仍允许运行allowFormVisibleNotify允许卡片可见性通知runningResourcesApply / resourcesApply资源调度如帧率档位申请2.2 特权是如何生效的特权和普通权限走的不是一条链路。普通权限是申请—校验—授予的运行时流程特权则是系统在安装时直接往应用的安装信息里写若干个标志位之后各子系统在运行时读这些标志位来决定行为。整条链路如下否是install_list_capability.json设备侧特权表BMS 开机扫描按 bundleName 匹配条目app_signature 与 HAP 签名证书SHA-256 是否全等整条条目静默丢弃无报错、无日志映射为 ApplicationInfo 标志位allowAppDesktopIconHide → hideDesktopIcon随安装信息落盘bundleInfo 数据库Launcherhome 意图查询时过滤 → 无图标AMS / AppMgrScheduler允许拉起 ServiceExtension、DataExtension资源调度 / 账户 / CESkeepAlive、singleton、allowCommonEvent四点要记住校验发生在扫描阶段且是全等比对。比对对象是 HAP 签名证书的 SHA-256 指纹与app_signature必须完全一致大小写、有无冒号都算不一致。不匹配时整条条目被丢弃不留任何错误日志只能靠现象反推。配置名和运行时字段名不是一回事。配置里写的是allowAppDesktopIconHide落到ApplicationInfo后bm dump出来叫hideDesktopIcon。按配置名去搜 dump 或搜源码是很容易卡住的一步。优先级设备侧配置高于签名 profile。同一项特权若两处都声明以install_list_capability.json为准。但反过来要注意通用特权AllowAppDesktopIconHide、AllowAppDataNotCleared等也可以写在签名 profile 的app-privilege-capabilities里那是跟着签名走的光删 JSON 里的字段撤不掉得换 profile 重签。标志位属于安装态数据。它随 bundleInfo 落盘改 JSON 不会热更新到已装应用身上——必须让应用重新走一遍安装流程这就是前面反复强调改完必须重装的底层原因。配置字段与 dump 中实际字段的对照下表为设备上逐条bm dump验证的结果配置字段dump 中能搜到的字段运行时消费方allowAppDesktopIconHidehideDesktopIconLauncherhome 意图查询时过滤该应用keepAlivekeepAlive顶层另有汇总位isKeepAlive资源调度、后台任务管理singletonsingleton账户子系统多用户安装策略allowAppUsePrivilegeExtension无同名字段只能看extensionInfos能否拉起AMS / AppMgrSchedulerallowCommonEvent无同名字段CES静态订阅公共事件后两项在 dump 里搜不到同名字段验证方式只能是能不能用特权扩展看 picker / service 类扩展能否正常拉起静态订阅看事件能不能收到。2.3 实测特权在设备上长什么样以设备上预置的文件管理器com.ohos.filemanager为例配置条目是{bundleName:com.ohos.filemanager,app_signature:[0F1E2D3C4B5A69788796A5B4C3D2E1F00F1E2D3C4B5A69788796A5B4C3D2E1F0],allowAppUsePrivilegeExtension:true,allowAppDesktopIconHide:true}查设备上的实际状态Git Bash / WSL 下最省事管道直接交给设备端执行hdc shellbm dump -n com.ohos.filemanager | grep -iE hide|desktop|fingercmd 下没有grep两条替代写法:: 写法一findstr 在本地过滤 hdc shell bm dump -n com.ohos.filemanager | findstr /i hideDesktopIcon fingerprint :: 写法二让管道在设备端跑正则用单引号外层整体加引号 hdc shell bm dump -n com.ohos.filemanager | grep -iE hide|desktop|finger输出fingerprint: 0F1E2D3C…C3D2E1F0, hideDesktopIcon: true,指纹与配置完全一致、hideDesktopIcon为true说明这条特权已经生效。注意这个组合会带来一个很容易被误判为安装失败的现象应用能正常拉起但桌面上找不到图标——原因和处理见后面的案例一节。把该条目删掉并重启设备后同一条命令返回hideDesktopIcon: false, keepAlive: false, singleton: false,同一个应用、同一份签名唯一的变量就是 capability 里那一行配置标志位随之翻转——这就是特权生效最直接的证据。2.4 两个注意点签名指纹必须与 HAP 实际签名完全一致否则整条配置静默不生效。指纹不匹配不会报错只能靠现象反推。指纹有两种格式绝大多数条目是证书的 SHA-256 大写 hex少数条目如com.ohos.screenshot用bundleName_Base64串这种对 profile 证书指纹的特殊写法。新增条目时照抄同款应用的格式最稳妥。2.5 真实踩坑9568344带 service 型特权扩展的应用典型如录屏如果没有allowAppUsePrivilegeExtension: true安装直接失败错误码9568344。当时排查就是hilog过滤C01121 / BMSInstaller定位的——安装类问题优先看这个 tag。3. install_list_permissions.json —— 权限预授予OpenHarmony 的权限体系里应用能拿到什么权限由它的 APL 等级normal / system_basic / system_core和 profile 里的 ACL 声明决定。本文件相当于系统侧的白名单通道在安装时直接给指定应用授予权限可以超出其 ACL 声明装完即是已授权状态不弹用户授权框。[{bundleName:com.ohos.screenrecorder,app_signature:[05BCE31A...],permissions:[{name:ohos.permission.WRITE_IMAGEVIDEO,userCancellable:true},{name:ohos.permission.MICROPHONE,userCancellable:true}]}]字段说明bundleName app_signature定位应用的钥匙指纹要求同上一个文件不匹配则静默失败。permissions[].name权限名。预授的通常是user_grant类权限麦克风、媒体读写、定位等预授后不再弹窗。userCancellabletrue用户可以在设置-权限管理里关掉false用户不可关闭。注意本文件最外层是数组[ ]和其它几个文件不同。指纹怎么来对应用签名证书算 SHA-256去掉冒号、转大写openssl x509-insignCert.pem-noout-fingerprint-sha256# 输出形如 SHA256 Fingerprint05:BC:E3:1A:... → 去冒号转大写即 05BCE31A...最大的坑改完这个文件必须重装应用才生效。授权动作发生在 BMS 安装流程里对已装应用改文件不会补授权。正确操作# 1. 卸载system 应用卸载后包仍在 /system/app重启会被重新扫描安装hdc shell bm uninstall-ncom.example.myapp# 2. 重启BMS 重新安装此刻读取新 JSON 完成预授hdc shellreboot# 3. 验证授权状态hdc shell bm dump-ncom.example.myapp# 在输出中找到对应权限确认 grantState 为已授权如果设备方便恢复出厂设置也能达到同样效果所有预置应用重新走一遍安装。4. default_app.json —— 默认应用默认应用浏览器、输入法、拨号、短信等按类型的默认绑定的预置配置。该文件内容为空数组[]即未做任何预置全部使用系统内建默认。这个文件一般不用动且其 schema 在不同版本间差异较大真要配置先对照当前版本 bundle_framework 源码确认格式。5. uninstall_list.json —— 默认卸载与恢复{uninstall_list:[],recover_list:[]}uninstall_list列出的 bundleName 在开机装完后随即置为已卸载状态——包预置在系统分区里但不出现在桌面、不可用。典型场景是运营商/渠道要求出厂不露出的应用。recover_list列出的 bundleName 允许从已卸载态被恢复安装比如用户主动点击或云端下发恢复。和removable的区别容易混淆控制什么install_list.json 的 removable用户能不能卸载uninstall_list.json 的 uninstall_list系统默认就以卸载态存在实战串联预置一个带权限的系统应用把 5 个文件串起来走一遍真实流程新增一个带 service 扩展、需要麦克风和媒体写入权限的系统应用放包HAP 推到/system/app/com.ohos.screenrecorder/install_list.json加条目{ app_dir: ..., removable: false }install_list_capability.json加条目开启allowAppUsePrivilegeExtension: true否则 service 扩展安装报 9568344install_list_permissions.json加条目预授MICROPHONE、WRITE_IMAGEVIDEO指纹填签名证书 SHA-256重装生效bm uninstall -n com.ohos.screenrecorder→ 重启验证bm dump -n com.ohos.screenrecorder确认权限已授权、扩展已装上有异常就看hilog | grep -E C01121|BMSInstaller。案例装好了、能拉起但桌面没有图标现象预置扫描或bm install都成功aa start能把界面拉起来桌面上就是找不到图标。结论这大概率不是 bug而是allowAppDesktopIconHide在按设计工作。官方对入口图标有一套明确的判定规则Stage 模型入口 Ability 是否配 icon/label是否具备隐藏图标特权桌面表现配了没有显示该 Ability 的 icon label点击进首页配了有不显示桌面查询不返回该应用没配没有用 app.json5 的 icon label点击进应用详情页没配有不显示关键点“具备该特权就等于从桌面消失”没有允许但可选的中间态。系统对无图标应用有严格管控——防止恶意应用故意不留入口、让用户找不到也无法卸载所以除预置应用外普通应用根本不允许隐藏图标。排查路径是否否是否是装完能拉起桌面没有图标bm dump 里hideDesktopIcon 是否为 true符合设计具备隐藏图标特权Launcher 查询时直接过滤要图标删掉 allowAppDesktopIconHide保留其它字段 → 重装入口 Ability 的 skills 是否含entity.system.home home action补 skills 声明后重装是否装在当前用户 / U0bm install -p xxx.hap -u 0Launcher 列表缓存未刷新重启设备刷新设备上的实测数据com.ohos.filemanager与本文 2.3 节同源。这里做了一组 A/B 对照——其它条件全部不动只删掉 capability 里那一条allowAppDesktopIconHide项改动前条目存在改动后条目删除 重启hideDesktopIcontruefalsefingerprint与配置一致此处省略不变isSystemApp / appDistributionTypetrue / os_integration不变removablefalse不变mainElementNameMainAbility不变入口 skillsaction.system.home entity.system.home不变桌面表现查不到图标但能拉起图标回到桌面这组对照把链路验证死了签名、系统应用身份、入口声明全都没变桌面表现却随一个布尔值反转——图标有无完全由hideDesktopIcon决定与装没装上无关。整个链条就此闭合签名指纹匹配 → 特权表把hideDesktopIcon写进ApplicationInfo→ Launcher 按 home 意图查询时把它过滤掉 → 桌面无图标但 Ability 完全可用。要恢复图标核心只有一步把该条目的allowAppDesktopIconHide删掉保留app_signature和allowAppUsePrivilegeExtension删掉指纹会让整条失效连带特权扩展也没了hdc shellfind /system -name install_list_capability.jsonhdc shellmount -o remount,rw /hdcfilerecv /system/etc/app/install_list_capability.json ./install_list_capability.json.bak# 本地删掉 allowAppDesktopIconHide 字段后推回hdcfilesend ./install_list_capability.json /system/etc/app/install_list_capability.json hdc shellchmod 644 /system/etc/app/install_list_capability.jsonhdc shellreboot重启后再grep hideDesktopIcon验证应从true变为false或字段消失。对removable: false的预置应用若重启后标志位仍是true说明 BMS 跳过了已装应用需要bm uninstall -n 包名让它重装一次。要的是无图标、只能被拉起那现在就是正确状态一行都不用改。隐藏图标应用的正常唤起方式是显式 wanthdc shellaa start -b com.ohos.filemanager -a MainAbility排错速查现象大概率原因处理改了 permissions/capability 但没生效应用没重装或指纹不匹配bm uninstall后重启核对指纹安装报错 9568344service 型特权扩展缺 allowAppUsePrivilegeExtensioncapability 中加该项并重装加了 install_list 条目但没装上app_dir 不存在 / 目录里没有 HAP / 应用此前已装过被跳过核对路径与 HAP卸载后重启改了文件整个功能都异常JSON 语法错误整个文件不生效本地校验 JSON 后再推送改了 /system/etc/app 下的文件却没作用高优先级分层目录有同名文件覆盖param get const.cust.config_dir_layer查分层改优先级最高那份装完能拉起但桌面没有图标具备hideDesktopIcon特权配置里allowAppDesktopIconHide: true属设计行为见案例一节要图标就删字段后重装桌面图标点进去是应用详情页入口 Ability 未配 icon/label或 skills 缺 home 意图补abilities的 icon/label 与skills后重装只删了 JSON 字段图标仍不出现通用特权AllowAppDesktopIconHide写在签名 profile 里换不带该特权的 profile 重签 HAP通用注意事项分层覆盖不是合并预置配置支持 system / chipset / sys_prod / chip_prod 多层目录越靠后优先级越高同名 JSON整文件覆盖低优先级那份。只改/system/etc/app/里的文件可能根本不生效。/etc是指向/system/etc的符号链接两个路径是同一批文件编辑走真实路径/system/etc/app/即可。修改 system 分区前先mount -o remount,rw /。三份 install_list* 的生效规则记一句话list 管安装重启capability / permissions 管安装时刻必须重装。配置字段名与 dump 字段名不一致allowAppDesktopIconHide→hideDesktopIcon。查设备状态时按 dump 的名字搜否则会误判成特权没生效。改 system 分区文件前先hdc file recv备份到本地removable: false的预置应用一旦配错回滚只能靠重刷镜像。cmd 下没有grephdc shell xxx | grep会把管道交给本地 shell 执行而报不是内部或外部命令。要么用 Git Bash要么用findstr要么给整条命令套引号让管道在设备端跑。排查口诀装不上、授权失败先hilog | grep -E C01121|BMSInstaller。