Runtime Resource Overlay无法启用问题求助

问题现象 #

执行adb shell cmd overlay list命令后，输出显示RRO已安装但存在错误：

...
com.example.mytarget
--- com.example.myoverlay

---表示该RRO无法启用。进一步执行adb shell cmd overlay dump com.example.myoverlay得到以下结果：

com.example.myoverlay:0 {
  mPackageName...........: com.example.myoverlay
  mOverlayName...........: null
  mUserId................: 0
  mTargetPackageName.....: com.example.mytarget
  mTargetOverlayableName.: null
  mBaseCodePath..........: /system/product/overlay/myoverlays.apk
  mState.................: STATE_MISSING_TARGET
  mIsEnabled.............: true
  mIsMutable.............: true
  mPriority..............: 2147483647
  mCategory..............: null
  mIsFabricated..........: false
}
IDMAP OF com.example.myoverlay
<missing idmap>

系统提示STATE_MISSING_TARGET（目标未安装），但实际目标应用已存在，陷入困惑。

项目配置 #

项目结构 #

└── MyOverlays
    ├── AndroidManifest.xml
    └── res
        └── xml
            └── overlays.xml

AndroidManifest.xml内容 #

<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="https://schemas.android.com/apk/res/android"
    package="com.android.systemui">
    <application android:hasCode="false" /> 
    <overlay android:targetPackage="com.android.systemui"
                android:targetName="res.values.colors.xml"
                android:resourcesMap="@xml/overlays"
                android:priority="1"/>
</manifest>

overlays.xml内容 #

<overlay xmlns:android="http://schemas.android.com/apk/res/android" >
    <item target="color/global_actions_lite_background" value="#FFBF360C" />
    <item target="color/notification_primary_text_color" value="#55FF0000" />
</overlay>

设备信息 #

Android 12.1，索尼Xperia 1，LineageOS系统

解决方案 #

1. 修正RRO包名 #

AndroidManifest.xml中的package属性不能和目标包名com.android.systemui重复，改为自定义唯一包名，比如：

package="com.example.systemui.color.overlay"

2. 移除错误的targetName属性 #

android:targetName="res.values.colors.xml"是错误用法，该属性指向的是目标应用中定义的<overlayable>名称，而非资源文件路径。若目标应用未指定特定overlayable，直接删除该属性即可：

<overlay android:targetPackage="com.android.systemui"
         android:resourcesMap="@xml/overlays"
         android:priority="1"/>

3. 确保签名匹配 #

系统应用（如SystemUI）的RRO需要与目标应用使用相同的签名（或系统签名）。对于LineageOS，需使用对应版本的平台签名对RRO APK进行签名，否则系统会拒绝加载。

4. 检查安装权限与路径 #

将RRO APK放入/system/product/overlay/后，需设置正确的文件权限：

adb shell chmod 644 /system/product/overlay/myoverlays.apk

5. 重新安装并启用 #

卸载旧的overlay，重新安装后执行启用命令：

adb uninstall com.example.systemui.color.overlay
adb push myoverlays.apk /system/product/overlay/
adb reboot
adb shell cmd overlay enable com.example.systemui.color.overlay

内容的提问来源于stack exchange，提问作者Heimchen Heimelig