Android 10 APK升级时为何出现INSTALL_FAILED_TEST_ONLY错误？

Question

在Android 10（API 29）中，系统强化了安装安全策略：若APK的`AndroidManifest.xml`中声明了`android:testOnly="true"`（或构建时未显式设为`false`），且该APK已安装为非test-only版本，则升级安装会直接失败，并抛出`INSTALL_FAILED_TEST_ONLY`错误。此行为并非仅限于adb install，也影响通过PackageInstaller静默升级或Intent触发的安装流程。根本原因在于Android 10起强制校验已安装包与新包的`testOnly`属性必须严格一致——旧版允许覆盖，而Android 10+拒绝“从test-only升级为非test-only”或反之。常见诱因包括：使用debug build variant签名包用于灰度发布、CI流水线未正确配置`android.testOptions.unitTests.includeAndroidResources = true`导致Gradle自动注入`testOnly=true`、或手动修改`build.gradle`未同步清除`android:testOnly`属性。解决方案是确保发布/升级包均以`release`变体构建，且`AndroidManifest.xml`中显式声明`android:testOnly="false"`，或在`build.gradle`中添加`android { packagingOptions { exclude 'META-INF/*' } }`并验证`aapt dump badging app.apk | grep testOnly`输出为`false`。

Answer 1

```html

一、现象层：INSTALL_FAILED_TEST_ONLY 错误的典型表现

• 用户点击升级安装包时，界面静默失败，无明确提示；
• adb install -r 输出：Failure [INSTALL_FAILED_TEST_ONLY]；
• PackageInstaller API 调用 session.commit(...) 抛出 IntentSender.SendIntentException，日志中可捕获 INSTALL_FAILED_TEST_ONLY；
• 通过 Intent.ACTION_INSTALL_PACKAGE 启动安装后，系统弹出“应用未安装”提示（Android 10+ 默认不显示具体错误码）；
• 同一设备上，debug 包可首次安装，但无法覆盖已存在的 release 版本——反之亦然。

二、机制层：Android 10 安装校验的底层变更

自 Android 10（API 29）起，PackageManagerService 在 installStage() 阶段新增严格一致性校验逻辑：

if (pkgSetting != null && pkgSetting.pkg != null) {
    final boolean oldTestOnly = (pkgSetting.pkg.applicationInfo.flags & ApplicationInfo.FLAG_TEST_ONLY) != 0;
    final boolean newTestOnly = (parsedApk.applicationInfo.flags & ApplicationInfo.FLAG_TEST_ONLY) != 0;
    if (oldTestOnly != newTestOnly) {
        throw new PackageManagerException(INSTALL_FAILED_TEST_ONLY, "testOnly flag mismatch");
    }
}

该逻辑位于 frameworks/base/services/core/java/com/android/server/pm/PackageManagerService.java（AOSP 10.0 分支），取代了此前仅在 adb install 场景下宽松处理的策略。

三、诱因全景图：五类高频触发场景

序号	诱因类型	技术路径	隐蔽性
1	Debug Variant 灰度发布	CI 构建使用 ./gradlew assembleDebug 并签名分发	高（manifest 未显式声明，Gradle 自动注入 true）
2	单元测试配置污染	android.testOptions.unitTests.includeAndroidResources = true → 触发 testOnly=true 注入	极高（开发者常忽略此配置副作用）
3	Manifest 手动残留	<application android:testOnly="true"> 未清理	中（易被 code review 遗漏）
4	Flavor 继承错配	release flavor 未 override debug 的 testOnly 属性，导致继承 true	高（多 flavor 工程常见）
5	APK 重签名篡改	第三方加固/渠道包工具未同步清除 testOnly 标志位	极高（黑盒工具链难溯源）

四、诊断流程：从现象到根因的标准化排查链

graph TD
    A[安装失败] --> B{确认是否为升级场景？}
    B -->|是| C[获取已安装包 testOnly 状态]
    B -->|否| D[检查新包 manifest/testOnly 声明]
    C --> E[aapt dump badging installed.apk | grep testOnly]
    D --> F[aapt dump badging new.apk | grep testOnly]
    E --> G{值是否一致？}
    F --> G
    G -->|否| H[定位构建配置或签名环节]
    G -->|是| I[检查签名证书一致性及 targetSdkVersion]

五、工程化解决方案：覆盖构建、验证、监控全生命周期

1. 构建侧强约束：在 build.gradle 中显式关闭 testOnly（所有 flavor）：
   android { buildTypes { release { manifestPlaceholders = [testOnly: 'false'] } } }
2. Manifest 统一声明：<application android:testOnly="${testOnly}"> + resValue "string", "test_only_flag", "${testOnly}"
3. CI 流水线门禁：添加 shell 检查步骤：
   aapt dump badging app-release.apk | grep 'testOnly' | grep -q 'false' || exit 1
4. 灰度发布双轨制：debug 包仅允许 sideload 安装（adb shell settings put global verifier_verify_adb_installs 0），禁止 OTA 升级通道
5. APK 元数据审计工具：集成 apkanalyzer 自动提取 testOnly、targetSdkVersion、signature 三元组并存档

六、进阶避坑指南：五个被低估的细节

• Gradle 6.5+ 中 android.testOptions.unitTests.includeAndroidResources = true 会隐式启用 testOnly，即使未配置 signingConfigs；
• android:testOnly="false" 必须写在 <application> 标签内，写在 <manifest> 根节点无效；
• 使用 bundletool build-apks 生成的 APK，默认 testOnly=false，但若 base module 的 build.gradle 含 testOnly 配置，仍会被继承；
• Android Studio 的 “Generate Signed Bundle / APK” 向导默认使用 release variant，但若项目存在 custom task 覆盖 assemble，可能绕过该保障；
• 部分 OEM 定制 ROM（如 MIUI 12.5）在 Android 10 底层之上额外增强校验，要求 testOnly 与 debuggable 标志必须同向，需同步校验 ApplicationInfo.FLAG_DEBUGGABLE。

```