overlay 包扫描

本文面向已经读过 vendor 与 product 扫描、扫描签名校验的读者，继续追踪 Runtime Resource Overlay（RRO）如何从 overlay 目录进入 Android 17 的 PackageManager 和 OverlayManager。前文只需知道分区有 overlay 目录以及普通包会经过 ParsedPackage/PackageSetting；本文重点解释 overlay 的轻量发现、配置排序、分区 policy、签名校验、用户状态和 idmap 生效时机。

RRO 的“扫描”与“启用”不是同一个动作：OverlayScanner 读取 manifest 得到 ParsedOverlayInfo，OverlayConfigParser 读取 overlay/config/config.xml 得到启用/可变/优先级配置，PMS 仍然用普通 package scanner 把 APK 注册成 AndroidPackage，随后 OverlayManagerServiceImpl 才为每个用户建立或更新 OverlayInfo、生成 idmap 并通知目标包刷新资源。

读完后，读者应能从 InitAppsHelper.initSystemApps() 找到 overlay 配置初始化入口；能够解释同一个 overlay 为什么同时出现在 ParsedOverlayInfo、ParsedConfiguration、AndroidPackage 和 OverlayInfo 中；能够区分 system property 不匹配、config.xml 不合法、overlay 签名不匹配、target 缺失和 idmap 创建失败；还能够根据 code path、target、priority、mutable 和用户状态定位“扫描到了但没有生效”的问题。

1. 角色边界

1.1 发现与生效

源码文件：

frameworks/base/core/java/com/android/internal/content/om/OverlayScanner.java
frameworks/base/core/java/com/android/internal/content/om/OverlayConfig.java
frameworks/base/services/core/java/com/android/server/om/OverlayManagerServiceImpl.java

阶段	owner	主要数据	对外效果
目录发现	`OverlayScanner`	`ParsedOverlayInfo`	发现 overlay manifest 信息
配置解析	`OverlayConfigParser`	`ParsedConfiguration`	enabled、mutable、policy、配置顺序
PMS 包扫描	`InstallPackageHelper`	`AndroidPackage`、`PackageSetting`	包进入 PMS 包表和查询结构
用户态同步	`OverlayManagerServiceImpl`	`OverlayInfo`、`OverlayManagerSettings`	每个 user 的 overlay 状态
资源生效	`IdmapManager`/AssetManager	idmap、overlay paths	target package 读取覆盖资源

overlay APK 被 OverlayScanner 发现，不代表它已经启用；被 OverlayManagerServiceImpl 初始化，也不代表 idmap 一定创建成功。每一层都有自己的 owner、失败方式和可观察输出。

1.2 两种配置来源

Android 17 同时支持两种 overlay 配置来源：

system process 使用 PackageProvider，从 PMS 已扫描的 AndroidPackage 中取得 overlay manifest 字段，再按 OverlayConfigParser 读取配置文件；
zygote 使用 OverlayScanner 直接扫描分区 overlay 目录，建立可供 zygote 使用的静态 overlay 配置，但不包含分区目录外的静态 overlay。

这两个实例的输入不同，不能把 zygote 侧扫描结果当成 PMS 的完整包表。system instance 的 PackageManager 视图才是运行时 OverlayManager 的事实来源。

2. 目录发现

2.1 扫描信息

源码文件：frameworks/base/core/java/com/android/internal/content/om/OverlayScanner.java

java

/** Represents information parsed from the manifest of an overlay. */
public static class ParsedOverlayInfo {
    public final String packageName;
    public final String targetPackageName;
    public final int targetSdkVersion;
    public final boolean isStatic;
    public final int priority;
    public final File path;
    @Nullable public final File preInstalledApexPath;

    public ParsedOverlayInfo(String packageName, String targetPackageName,
            int targetSdkVersion, boolean isStatic, int priority, File path,
            @Nullable File preInstalledApexPath) {
        this.packageName = packageName;
        this.targetPackageName = targetPackageName;
        this.targetSdkVersion = targetSdkVersion;
        this.isStatic = isStatic;
        this.priority = priority;
        this.path = path;
        this.preInstalledApexPath = preInstalledApexPath;
    }

    @NonNull
    public File getOriginalPartitionPath() {
        return preInstalledApexPath != null ? preInstalledApexPath : path;
    }
}

ParsedOverlayInfo 是轻量 manifest 结果，不包含完整组件、权限或资源表。preInstalledApexPath 用于把更新 APEX 中的 overlay 归属回原始分区；普通 overlay 的原始路径就是自身 path。因此分区归属判断不能只看 APK 当前路径。

2.2 递归扫描

源码文件：frameworks/base/core/java/com/android/internal/content/om/OverlayScanner.java

java

public void scanDir(File partitionOverlayDir) {
    if (!partitionOverlayDir.exists() || !partitionOverlayDir.isDirectory()) {
        return;
    }

    if (!partitionOverlayDir.canRead()) {
        Log.w(TAG, "Directory " + partitionOverlayDir + " cannot be read");
        return;
    }

    final File[] files = partitionOverlayDir.listFiles();
    if (files == null) {
        return;
    }

    for (int i = 0; i < files.length; i++) {
        final File f = files[i];
        if (f.isDirectory()) {
            scanDir(f);
        }

        if (!f.isFile() || !f.getPath().endsWith(".apk")) {
            continue;
        }

        final ParsedOverlayInfo info = parseOverlayManifest(f, mExcludedOverlayPackages);
        if (info == null) {
            continue;
        }

        mParsedOverlayInfos.put(info.packageName, info);
    }
}

扫描行为是递归、后写覆盖：目录不存在、不可读、listFiles() 返回 null、非 APK 或 manifest 解析返回 null 都会被跳过；同包名后发现的 ParsedOverlayInfo 替换先前值。源码没有对 File[] 做排序，因此不能把文件系统枚举顺序当成稳定 priority 规则，priority 应由配置/manifest 和后续 OverlayConfig 逻辑解释。

2.3 Manifest 轻解析

源码文件：frameworks/base/core/java/com/android/internal/content/om/OverlayScanner.java

java

@VisibleForTesting
public ParsedOverlayInfo parseOverlayManifest(File overlayApk,
        List<Pair<String, File>> outExcludedOverlayPackages) {
    final ParseTypeImpl input = ParseTypeImpl.forParsingWithoutPlatformCompat();
    final ParseResult<ApkLite> ret = ApkLiteParseUtils.parseApkLite(input.reset(),
            overlayApk,
            FrameworkParsingPackageUtils.PARSE_IGNORE_OVERLAY_REQUIRED_SYSTEM_PROPERTY);
    if (ret.isError()) {
        Log.w(TAG, "Got exception loading overlay.", ret.getException());
        return null;
    }
    final ApkLite apkLite = ret.getResult();
    if (apkLite.getTargetPackageName() == null) {
        // Not an overlay package
        return null;
    }
    final String propName = apkLite.getRequiredSystemPropertyName();
    final String propValue = apkLite.getRequiredSystemPropertyValue();
    if ((!TextUtils.isEmpty(propName) || !TextUtils.isEmpty(propValue))
            && !FrameworkParsingPackageUtils.checkRequiredSystemProperties(propName, propValue)) {
        outExcludedOverlayPackages.add(Pair.create(apkLite.getPackageName(), overlayApk));
        return null;
    }
    return new ParsedOverlayInfo(apkLite.getPackageName(), apkLite.getTargetPackageName(),
            apkLite.getTargetSdkVersion(), apkLite.isOverlayIsStatic(),
            apkLite.getOverlayPriority(), new File(apkLite.getPath()), null);
}

这个入口只调用 ApkLiteParseUtils.parseApkLite()，并使用 PARSE_IGNORE_OVERLAY_REQUIRED_SYSTEM_PROPERTY 先拿到 required property，再由 checkRequiredSystemProperties() 决定是否排除。没有 targetPackageName 的 APK 被静默视为普通/非 overlay；property 不匹配的 APK 进入排除列表，而不是 mParsedOverlayInfos。