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.json

BMS（包管理服务）开机扫描的大致流程：

1. 扫描 /system/app/ 等预置目录下的 HAP；
2. 对照 install_list.json，安装其中尚未安装的应用；
3. 在安装这一刻 ，去 install_list_capability.json 应用特权能力、去 install_list_permissions.json 完成权限预授予；
4. 按 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_dir：HAP 所在目录（设备上的绝对路径）。目录必须真实存在且其中有 HAP，否则该条目安装失败，开机日志里能看到 BMS 扫描报错。
• removable：true 用户可卸载（卸载后可恢复）；false 系统级应用，不可卸载。只控制"能否卸载"，与权限、特权无关。

新增一个预置应用的完整步骤：

# 1. 重挂载 system 分区为可写
hdc shell "mount -o remount,rw /"

# 2. 推送 HAP
hdc file send MyApp.hap /system/app/com.example.myapp/com.example.myapp.hap

# 3. 修改 /system/etc/app/install_list.json，加入条目后推回（或设备上直接改）

# 4. 重启，BMS 扫描安装
hdc shell reboot

注意：这种方式只对"尚未安装"的应用生效；应用此前装过的话，BMS 扫描时会跳过，改动不会落到已装应用身上。

2. install_list_capability.json ------ 特权能力配置

有些能力应用无法通过 module.json5 申请，只能由系统侧预置授予，就配置在这里：

{
    "bundleName": "com.ohos.launcher",
    "app_signature": ["8E93863FC32EE238..."],
    "allowAppUsePrivilegeExtension": true,
    "allowAppDesktopIconHide": true
}

常用字段：

字段	含义
app_signature	签名证书指纹，SHA-256 大写十六进制、无冒号；可配多个对应不同签名环境
allowAppUsePrivilegeExtension	允许使用 service / push 等特权扩展类型
allowAppDesktopIconHide	允许隐藏桌面图标（无界面的后台/对话框类应用用）
allowCommonEvent	允许静态订阅指定公共事件，如 usual.event.SMS_RECEIVE_COMPLETED、usual.event.USER_ADDED
singleton	多用户下仅单实例
keepAlive	常驻保活
associatedWakeUp	允许被关联唤醒
allowAppRunWhenDeviceFirstLocked	首次锁屏后仍允许运行
allowFormVisibleNotify	允许卡片可见性通知
runningResourcesApply / resourcesApply	资源调度（如帧率档位）申请

两个注意点：

• 签名指纹必须与 HAP 实际签名完全一致，否则整条配置静默不生效。指纹不匹配不会报错，只能靠现象反推。
• 指纹有两种格式：绝大多数条目是证书的 SHA-256 大写 hex；少数条目（如 com.ohos.screenshot）用 "<bundleName>_<Base64串>" 这种对 profile 证书指纹的特殊写法。新增条目时照抄同款应用的格式最稳妥。

真实踩坑 ：带 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 类权限（麦克风、媒体读写、定位等），预授后不再弹窗。
• userCancellable：true 用户可以在设置-权限管理里关掉；false 用户不可关闭。
• 注意本文件最外层是数组 [ ]，和其它几个文件不同。

指纹怎么来：对应用签名证书算 SHA-256，去掉冒号、转大写：

openssl x509 -in signCert.pem -noout -fingerprint -sha256
# 输出形如 SHA256 Fingerprint=05:BC:E3:1A:... → 去冒号转大写即 05BCE31A...

最大的坑：改完这个文件必须重装应用才生效。 授权动作发生在 BMS 安装流程里，对已装应用改文件不会补授权。正确操作：

# 1. 卸载（system 应用卸载后包仍在 /system/app，重启会被重新扫描安装）
hdc shell bm uninstall -n com.example.myapp
# 2. 重启，BMS 重新安装，此刻读取新 JSON 完成预授
hdc shell reboot
# 3. 验证授权状态
hdc shell bm dump -n com.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	系统默认就以卸载态存在

实战串联：在 RT80 上预置录屏应用并预授权限

把 5 个文件串起来走一遍真实流程（新增一个带 service 扩展、需要麦克风和媒体写入权限的系统应用）：

1. 放包 ：HAP 推到 /system/app/com.ohos.screenrecorder/；
2. install_list.json 加条目 { "app_dir": "...", "removable": false }；
3. install_list_capability.json 加条目，开启 allowAppUsePrivilegeExtension: true（否则 service 扩展安装报 9568344）；
4. install_list_permissions.json 加条目，预授 MICROPHONE、WRITE_IMAGEVIDEO，指纹填签名证书 SHA-256；
5. 重装生效 ：bm uninstall -n com.ohos.screenrecorder → 重启；
6. 验证 ：bm dump -n com.ohos.screenrecorder 确认权限已授权、扩展已装上；有异常就看 hilog | grep -E "C01121|BMSInstaller"。

排错速查

现象	大概率原因	处理
改了 permissions/capability 但没生效	应用没重装，或指纹不匹配	bm uninstall 后重启；核对指纹
安装报错 9568344	service 型特权扩展缺 allowAppUsePrivilegeExtension	capability 中加该项并重装
加了 install_list 条目但没装上	app_dir 不存在 / 目录里没有 HAP / 应用此前已装过被跳过	核对路径与 HAP；卸载后重启
改了文件整个功能都异常	JSON 语法错误，整个文件不生效	本地校验 JSON 后再推送
改了 /system/etc/app 下的文件却"没作用"	高优先级分层目录有同名文件覆盖	param get const.cust.config_dir_layer 查分层，改优先级最高那份

通用注意事项

1. 分层覆盖，不是合并 ：预置配置支持 system / chipset / sys_prod / chip_prod 多层目录，越靠后优先级越高，同名 JSON 整文件覆盖 低优先级那份。只改 /system/etc/app/ 里的文件可能根本不生效。
2. /etc 是指向 /system/etc 的符号链接，两个路径是同一批文件，编辑走真实路径 /system/etc/app/ 即可。
3. 修改 system 分区前先 mount -o remount,rw /。
4. 三份 install_list* 的生效规则记一句话：list 管安装（重启），capability / permissions 管安装时刻（必须重装）。

排查口诀：装不上、授权失败，先 hilog | grep -E "C01121|BMSInstaller"。