修复 Capacitor 应用中 Google Play 代码混淆率低于 25% 的问题

Play Console 现在会对 Capacitor Android 应用发出以下警告： 应用优化低于我们的阈值，通常伴随着 代码混淆 的问题 3%。Google 要求至少实现 25% 混淆、优化和缩减。强制执行将于 2027 年 2 月开始，未达标可能会降低应用曝光率和发布选项。

Android vitals 中的警告如下所示：

Google Play Console Android vitals 警告显示混淆率为 3%，低于 25% 的应用优化阈值，修复截止日期为 2027 年 2 月

这是一个原生 Android DEX 问题。这与你的 Vue、React 或 Angular bundle 无关。 Capgo Live Update 也不会改变这一分数。你需要在 Android Gradle release build 中修复它，然后上传新的 App Bundle。

Google 在衡量什么

Google Play 会检查 DEX （在你的 Android App Bundle 中）：已编译的 Java 和 Kotlin 代码，包括 Capacitor、plugins 和 AndroidX。从 2027 年 2 月起，DEX 超过 10 MB 的应用必须在以下三项上都达到 25% 标准：

指标	含义	导致低分的常见 Capacitor 原因
代码混淆	将类、字段和方法名重命名为短名称	`minifyEnabled` 仍然是 `false`
优化	R8 会内联、合并并重写字节码	默认 `proguard-android.txt` 包含 `-dontoptimize`
缩减	移除未使用的类和方法	Resource/code 缩减从未启用

Play 读取 r8.json 使用 Android Gradle Plugin 8.10 或更高版本的最新补丁构建时。否则会使用 mapping.txt，然后使用 DEX 启发式算法。发布时关闭混淆的 Capacitor 应用几乎没有 mapping 文件，因此 Play 会看到可读名称，并报告几个百分点的混淆率（通常来自已混淆的 library AARs 残留）。这与 3% vitals 评分相符。

官方政策： Play Console 技术质量要求。实现细节： DEX code 优化以及使用 R8 启用应用优化.

为什么 Capacitor 应用通不过这项检查

Capacitor Android 模板仍自带 release 构建无需 R8：

buildTypes {
    release {
        minifyEnabled false
        proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
    }
}

这是以下文件中的默认值： android-template/app/build.gradle. Debug 构建应保持现状。如果你要发布到 Play Store，Release 构建则不应如此。

你的 JavaScript 已经过 Vite 或 webpack 压缩。Play 不会将其计入。只有原生 DEX 名称、未使用的原生 code 以及 R8 优化才会被计入。

第 1 步 — 为 Release 版本开启 R8

打开 android/app/build.gradle (Groovy 是 Capacitor 默认方式) 并修改 发布版 代码块中：

buildTypes {
    release {
        minifyEnabled true
        shrinkResources true
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
}

如果模块使用 Kotlin DSL ("build.gradle.kts):

buildTypes {
    getByName("release") {
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(
            getDefaultProguardFile("proguard-android-optimize.txt"),
            "proguard-rules.pro"
        )
    }
}

三个细节至关重要：

minifyEnabled true 是实际运行 R8 (shrink + obfuscate + optimize) 的部分。
shrinkResources true 移除未使用的 Android 资源。它需要进行代码压缩。
对于此 R8 配置，请使用 proguard-android-optimize.txt. proguard-android.txt 发布 -dontoptimize，这会阻碍 R8 优化并导致 AGP 9 失败。Play 允许使用任何 shrinker；Capacitor 应用应使用带有默认优化设置的 R8。请查看修复 Capacitor 插件 AGP 9 构建报错插件是否仍在引用旧文件。

不要设置 minifyEnabled true 开启 debug。仅在 Release 模式下使用可保持本地运行速度并确保堆栈跟踪（stack traces）清晰可读。

步骤 2 — 不要禁用 R8 full mode

打开 android/gradle.properties 如果存在该行，请将其删除：

android.enableR8.fullMode=false

AGP 8+ 已默认启用 full mode。保留该标志会限制优化效果。

同时搜索 android/app/proguard-rules.pro (以及任何额外的 -include 文件) 用于：

-dontobfuscate
-dontoptimize
-dontshrink
-keep class ** { *; }

即使你切换了设置，这些规则仍会导致 Play 评分降低。 minifyEnabled除非有记录在案的临时理由，否则请删除它们。

第 3 步 — 仅保留 Capacitor 插件，而非整个 App

R8 使用反射元数据。Capacitor 插件通过注解进行发现，因此需要 keep rules。 通常你不需要手动添加它们。 自 Capacitor 3.2.3 版本起， @capacitor/android 已内置 consumer ProGuard rules 用于保留：

@CapacitorPlugin 类 (classes)， @PluginMethod、权限及 Activity 回调
继承自以下类的 com.getcapacitor.Plugin
旧版 @NativePlugin 以及 Cordova 插件类

保持在当前的 Capacitor 6/7/8 版本线上，以确保这些 consumer 规则生效。

在以下位置添加额外规则： android/app/proguard-rules.pro 仅针对可在 Release build 中复现的崩溃进行排查。精准胜过泛化：

# Good: one misbehaving plugin package
-keep class com.mycompany.myplugin.** { *; }

# Bad: this will tank obfuscation and shrinking
-keep class com.getcapacitor.** { *; }
-keep class ** { *; }

If a third-party plugin still crashes after a targeted keep rule, update the plugin, then consider a maintained alternative from the Capgo 插件目录，或者咨询 Capgo 咨询来修复它。

官方 Capacitor 说明：使用 ProGuard.

第 4 步 — 构建正式 Release Bundle

Debug APK 的混淆率仍显示为 ~0%。Play Store 仅对你上传的内容进行评分。

在项目根目录下：

npm run build
npx cap sync android
cd android
./gradlew bundleRelease

如果没有 release signingConfig，这些任务仍会成功，但会生成未签名的 .aab。请在上传到 Play Store 之前先在 Android Studio 中进行签名。

安装一个 Release APK 到设备上 (./gradlew assembleRelease，然后是下方的 APK app/build/outputs/apk/release/)。一个 .aab 是 Play 上传格式，不能直接 sideload。请测试原生 plugin（camera, push, file, billing, auth）。R8 的 bug 不会在 npx cap run android debug 会话中出现。

执行完上述 Gradle 命令后（你当前处于 android/），请确认 R8 是否已实际运行：

app/build/outputs/mapping/release/mapping.txt
app/build/outputs/mapping/release/configuration.txt
在 AGP 8.10 或更高版本的最新补丁中， r8.json 在 App Bundle 内部

这些 release 文件夹是默认的 Capacitor variant。如果使用了 product flavors，mapping 文件位于 variant 名称下（mapping/freeRelease/）。APK 位于 apk/<flavor>/release/ （例如 apk/free/release/).

如果 mapping.txt 缺失，你可能进错了 variant 文件夹，或者 CI 构建时 debug，或者 R8 运行时使用了 -dontobfuscate。请重新检查 minifyEnabled true 开启 release 并确保 keep rules 没有禁用混淆。

第 5 步 — 保持崩溃报告的可读性

如果没有 mapping 文件，混淆后的 stack traces 将毫无用处。请为 mapping.txt 每个 Play 版本保留：

Play Console： 测试和发布 → App bundle explorer → 下载 → 资源，然后 upload mapping.txt 如果尚未关联。
Firebase Crashlytics / Sentry：在 CI 流程中上传相同的 mapping 文件。

Android Studio / AGP 通常会将 mapping 嵌入到 .aab。在首次优化上传后，仍需检查 Assets 标签页。

第 6 步 — 上传并重新检查 Play

上传新的 .aab 到内部测试轨道（无需发布到生产环境即可刷新评分）。打开：

测试和发布 → App bundle 资源管理器 针对该版本
DEX 大小以及混淆 / 优化 / 缩减百分比
监控与改进 → Android vitals Play 会在发布新版本后进行分析

你需要 每项指标达到 25% 这三个指标，而不仅仅是混淆。启用 R8 后， proguard-android-optimize.txt 通常会让 Capacitor 应用的混淆率从个位数跃升，使三项指标均远超 25%。

Play 仅在 强制执行 当应用的 DEX 超过 10 MB（游戏为 50 MB）时，执行 25% 的底线要求。即使低于该标准，优化也是值得的：更小的 DEX、更低的内存占用、更快的启动速度。

如果你仍低于 25%

R8 已开启，但 Play（或本地分析器）仍显示评分较低。通常是因为保留规则（keep rules）写得太宽泛了。

打开 R8 配置分析器如果你的 Android Gradle Plugin 版本为 9.3 或更高 —— assembleRelease 然后写入 configanalyzer.html 旁边 mapping.txt。在 AGP 9.2 及更早版本中，跳过该 HTML 文件，改用 mapping.txt、APK Analyzer 以及 Play 的 App bundle explorer。
根据规则冻结 App 的程度对 keep 规则进行排序。无法编辑的库消费者规则是正常的。App 级别的 -keep class com.foo.** { *; } 则不然。
打开 .aab 在 Android Studio APK Analyzer 中，选择体积较大的 .dex 文件，并切换反混淆名称（需要 mapping.txt）。如果某些包依然体积巨大且清晰可读，说明应该停止对这些包进行整体保留。
更新仍在使用引用的插件 proguard-android.txt。该文件会阻碍 AGP 9 的优化，在旧版插件中也是一个危险信号。

不要试图通过缩小 DEX 来“修复”低分， minifyEnabled false 并寄希望于启发式算法发生变化。Google Play 需要的是缩小体积、优化以及以及混淆。

这并不能替代

JavaScript 代码压缩 中的 vite.config.ts 无法改变这一指标。
Capgo 实时更新 他们交付的是 HTML/JS/CSS，并不会重新构建 DEX。一旦商店二进制文件启用了 R8，你仍然可以通过 OTA 发送 JS 修复。但混淆检查本身需要进行一次原生的 Play upload。
16 KB 页大小 是 Google Play 的另一项原生要求。请参阅 Android 16 KB 页大小.

如果你已经使用以下方式构建 Android： Capgo 构建，请修改 android/app/build.gradle 仓库中的内容。下次云端构建将启用 R8。你不需要更改 Play pipeline，只需确保生成的 release binary 开启了 minification 即可。如果你使用 GitHub Actions 进行 Android 构建，逻辑也是一样的：workflow 必须执行 assemble 发布版，而不是 debug。

常见问题

启用 R8 会破坏我的 Capacitor 插件吗？

可能会，如果插件使用了 reflection 且没有提供 consumer keep rules。核心 Capacitor 已经保留了插件类。请测试 release build，并添加一个 缩小范围 只对导致崩溃的包保留 keep 规则。如果该插件已停止维护， Capgo 咨询可以 fork 并保持可构建。

是否 `npx cap run` 证明我通过了检查？

不是。那个命令用的是关闭 R8 的 debug build。请使用 bundleRelease / 已签名的 Play 上传包。

我们已经设置了 `minifyEnabled true` 但还是看到 3%。为什么？

搜索 -dontobfuscate, proguard-android.txt, android.enableR8.fullMode=false，以及全局 -keep 规则。确认 CI 上传的是混淆后的 AAB，而非旧的构建产物。

我们需要用 ProGuard 而不是 R8 吗？

不需要。R8 是 Android Gradle Plugin 的 shrinker，它支持读取 ProGuard 风格的规则文件。Google Play 文档允许使用任何 shrinker；而 Capacitor 应用应当使用 R8。

清单

release { minifyEnabled true; shrinkResources true }
proguard-android-optimize.txt （不是 proguard-android.txt)
否 -dontobfuscate / -dontoptimize / 全局应用 -keep class **
Capacitor 3.2.3+ 以确保插件消费者规则生效
Release 构建产物 mapping.txt
在 Release 安装包上测试过的 Native plugins
新增 .aab 已上传；mapping 文件已在 App bundle explorer 中附带
混淆、优化与缩减，各项均低于 25%

这就是 Play Console 的完整警告：Capacitor 关闭了 R8，导致 Play 开始计算 DEX，只需修改一行 Gradle 发布配置并重新上传即可修复。

从“修复 Capacitor 应用中 Google Play 混淆率低于 25%”的问题

如果你正在使用 修复 Capacitor 应用中 Google Play 代码混淆率低于 25% 的问题 到规划 Android 应用商店发布，并将其与 Capgo Native Build 用于发布 App Bundles， Capgo CI/CD 用于 upload 流水线， CI/CD 集成用于实现细节，使用 GitHub actions 实现 Capacitor Android 自动化构建用于自托管 pipeline，以及 Capgo 咨询如果启用 R8 后插件出现故障。