定制问题排查：overlay、属性与白名单

前五章把定制方式讲完了。这一章把它们串成排障链：overlay 不生效、属性不生效、 白名单不生效、系统应用能力缺失，按什么顺序查。

先确认产物是否进入正确分区和运行环境，再检查 idmap/overlay 状态、属性读取时机、进程缓存 与权限白名单。源码修改正确但产物未加载，是系统定制中最常见的假线索之一。

先验证配置是否加载，再判断逻辑

常见误解	正确理解
定制不生效就是文件没放对	可能是状态、映射、权限、签名或生效时机问题
overlay 失败看应用日志	先看 cmd overlay 与 idmap 状态
白名单报错都是权限名写错	可能是包名、签名、目录或版本差异

核心结论

1. 三类故障：资源（overlay）、行为（属性/设置）、能力（白名单/签名）。
2. 通用排障顺序：类型 → 链路 → 状态 → 根因。
3. overlay 先查启用、idmap、资源名与优先级。
4. 属性先查来源、读写权限与生效时机。
5. 白名单先查目录、签名、包名与权限清单。

排障主链

逐步解释：

1. 分类：先判断是资源、行为还是能力问题。
2. 链路：按对应机制的生效链路逐段检查。
3. 状态：用命令确认当前状态。
4. 修复：针对断点修复并回归。

常用命令与证据

环境：开发设备或模拟器；部分命令需要 root。

adb shell cmd overlay list
adb shell cmd overlay dump <overlay包名>
adb shell getprop | grep -iE "persist|ro\."
adb shell settings get global <key>
adb shell dumpsys package <包名> | grep -E "signatures|priv|allowlisted"
adb logcat -v threadtime | grep -E "overlay|idmap|privapp-permissions"

证据	含义	下一步
overlay 未启用	资源未生效	enable 并重启
idmap 失败	映射异常	查 target 与资源名
属性值为空/旧值	未写入或未重启	查来源与生效时机
无 allowlisted 记录	白名单未过	查签名与文件
logcat privapp 报错	白名单遗漏	补权限清单

常见场景与定位思路

场景一：overlay 不生效

先 cmd overlay list 确认启用，再 dump 查 idmap 与 target；检查资源名与目标包一致， 最后确认优先级与 overlayable 策略。

场景二：属性改了没反应

确认属性名与来源（ro/persist）、写权限，以及生效时机（需重启或服务重读）。persist 属性要验证重启后保留。

场景三：系统应用特权权限缺失

对照“目录、签名、白名单”三项；看 logcat 是否有 “not in privapp-permissions”， 再核对包名与权限名。

场景四：SystemUI 定制没变化

先确认 overlay 状态，再重启 SystemUI；若仍无效，检查资源是否被更高优先级 overlay 覆盖。

常见误区

1. “定制不生效就是文件位置问题”：按链路查状态。
2. “overlay 失败看应用日志”：先看 overlay 管理状态。
3. “属性改完立即生效”：注意生效时机。
4. “白名单报错只查权限名”：包名、签名、目录都要查。

延伸问题

1. 如何自动化验证 overlay 与白名单？
2. 多 overlay 优先级如何设计与排障？
3. 升级后定制丢失可能是什么原因？
4. 如何审计定制项的副作用与安全影响？

源码入口

文件	关键位置	作用
OverlayManagerService.java	overlay 状态	资源覆盖
system/core/init/property_service.cpp	属性服务	属性
PackageManagerService.java	白名单校验	特权
cmd overlay / getprop	命令行	状态检查

公共路径沿用本系列各章。行号以 r75 检索为准。

需要扩展到通用系统证据时，见 系统调试与排障。