修复 Capacitor 插件 AGP 9 构建报错

如果你的 Capacitor 如果你在升级到 Android Gradle Plugin 9 (AGP 9) 后发现 plugin 开始构建失败，你可能遇到了一个虽小但很关键的 Gradle 配置问题。

本文专门针对以下常见的搜索意图：

Capacitor 插件在 AGP 9 下的构建错误
Android Gradle Plugin 9 导致 Capacitor 插件构建失败
proguard-android.txt 未找到
AGP 9 getDefaultProguardFile error
升级 AGP 后 Capacitor Android 构建失败

简而言之：

proguard-android.txt 在 AGP 9 的 plugin 构建中，它已不再是安全的默认基准。
切换到 proguard-android-optimize.txt.
重新构建并验证。

了解长远影响也很重要，特别是当你维护多个插件或大型 Capacitor 工作区时。本文将涵盖：

Android 和 AGP 在构建链中的角色
Capacitor 是什么以及插件构建的工作原理
什么是 Capgo 以及为什么它对发布可靠性至关重要
导致旧插件模板失效的 AGP 9 具体变更
针对单个或多个仓库的安全迁移策略

在此语境下，Android 指的是什么？

Android 既是一种操作系统，也是一个构建生态系统。当你通过 Android 发布 Capacitor 应用或插件时，你的项目会经过：

Gradle 作为构建系统。
Android Gradle Plugin (AGP) 作为 Android 特有的 Gradle 集成。
用于打包、压缩、代码检查及生成 SDK 的 Android 工具链 .aar, .apk，或 .aab 输出结果。

当 AGP 版本更新时，某些默认设置和内部文件也会随之改变。如果插件配置指向了已移除或弃用的基准，那么原本适用于 AGP 8 的配置在 AGP 9 上可能会失效。

什么是 Capacitor？

Capacitor 是一种跨平台运行时，让你能够使用 Web code (TypeScript, JavaScript, HTML, CSS) 构建 iOS/Android 应用，同时仍能调用 native APIs。

Capacitor 应用通常包括：

Web 层（你的 UI 和业务逻辑）
原生 shell（ios/, android/)
向 JavaScript 暴露原生功能的插件

每个插件都有自己的原生构建配置。在 Android 上，这意味着每个插件都包含一个 android/build.gradle 文件，AGP 必须正确解析并编译。

如果插件的 Gradle 设置过时，即使你的 Web code 是正确的，整个 App 构建也可能会失败。

什么是 Capgo？

Capgo 提供围绕 Capacitor 交付与运维的工具：

Live Updates 用于 Web bundle 变更
插件生态与原生功能包
面向 Capacitor 团队的 CI/CD 友好更新工作流

即便有了 Live Update，Native Build 的稳定性也绝不能妥协。你仍然需要干净的 Android 构建来完成：

App Store / Play Store 版本发布
原生插件升级
平台 SDK 迁移
团队上手培训与 CI 可靠性

这就是为什么 AGP 9 兼容性修复至关重要：它们能确保你的插件层稳健可靠，从而让交付 pipeline 保持可预测性。

为什么 AGP 9 会破坏旧版插件配置

许多插件模板在历史上一直使用：

proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'

在 AGP 9 环境下，这种旧有的基准引用可能会失效，因为旧文件不再保证出现在旧版模板/配置所预期的位置。

典型症状包括在以下阶段出现 Gradle 错误： assemble, lint，或 build 这些错误通常指向缺失的 ProGuard 基准资源或无效的默认文件引用。

背景速览：ProGuard、R8 与 baseline 文件

R8 是 Android 构建中现代化的 code 代码缩减/优化工具。
proguard-rules.pro 是您的项目/插件自定义 keep 规则。
getDefaultProguardFile(...) 注入 Android 提供的 baseline。

当您引用：

proguard-android.txt -> 旧版、极简 baseline
proguard-android-optimize.txt -> 现代优化版 baseline（当前配置的推荐默认值）

为了兼容 AGP 9，切换到 proguard-android-optimize.txt 是实际有效的修复方案。

一行代码修复

更新插件和 app 模块的 Gradle 文件：

proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'

至少检查以下内容：

android/build.gradle 每个插件中
example-app/android/app/build.gradle 插件仓库中
任何用于生成新插件 Gradle 配置的生成器/模板文件

单个插件的迁移指南

1. 找到旧的引用

rg -n "proguard-android\\.txt" android example-app

2. 进行替换

perl -pi -e "s/proguard-android\\.txt/proguard-android-optimize.txt/g" \
  android/build.gradle example-app/android/app/build.gradle

3. 使用 Bun 进行验证

bun run verify:android

如果你的插件包含完整的验证脚本，请运行：

bun run verify

批量更新所有插件仓库

如果你在一个工作区中维护多个插件仓库，请实现自动化：

rg -l "proguard-android\\.txt" capacitor-* \
  --glob '!**/node_modules/**' \
  --glob '!**/.gradle/**' \
  --glob '!**/build/**' \
| xargs perl -pi -e "s/proguard-android\\.txt/proguard-android-optimize.txt/g"

然后验证受控的插件源码中不再使用旧文件：

for d in capacitor-*; do
  [ -d "$d/.git" ] || continue
  git -C "$d" grep -n "proguard-android\\.txt" -- || true
done

没有匹配项意味着已跟踪的插件文件中已丢失旧的基准引用。

Capgo 发布状态

我们已在所有官方 Capgo Capacitor 插件仓库和模板中完成了此次迁移：

插件 Android 模块现在引用 proguard-android-optimize.txt
插件示例 Android 应用也已更新
插件脚手架模板已更新，确保新插件默认兼容 AGP 9

这可以在问题进入 CI 之前，防止此类常见的 AGP 9 升级失败。

即使您现在的构建能通过，为什么这也很重要

如果出现以下情况，您可能不会立即看到失败：

您的 CI 缓存仍然掩盖了该问题
您的不同项目使用了混合的 AGP 版本
本地开发时仅重新构建了部分模块

但最终，clean build、新环境或升级后的 runner 都会暴露它。现在迁移就能消除隐藏的不稳定因素。

替换后 build 仍失败时如何排查

检查以下几点：

每个模块都已打补丁。查看 plugin 模块、app 模块、示例和模板资源。
共享脚本中没有第二处引用。搜索所有仓库（包括自定义 Gradle 脚本）。
缓存已清理。运行 ./gradlew clean 并重新 build。
AGP / Gradle / JDK 版本保持一致。使用 Android 文档中针对你的 AGP 版本支持的组合。
CI 使用与本地相同的版本。在 CI 中固定 JDK 和 Gradle wrapper 版本，以避免环境漂移。
不要只修复 node_modules。修复已跟踪的 plugin 源码，而不是临时依赖目录。

SEO FAQ：AGP 9 Capacitor plugin build 错误

如何修复 `proguard-android.txt` 在 AGP 9 中找不到？

替换为：

getDefaultProguardFile('proguard-android.txt')

改为：

getDefaultProguardFile('proguard-android-optimize.txt')

然后执行 clean rebuild。

升级到 Android Gradle Plugin 9 后，为什么我的 Capacitor 插件构建失败？

大多数失败是因为插件中遗留的 Gradle 配置 android/build.gradle 仍在引用 proguard-android.txt. AGP 9 项目应当使用 proguard-android-optimize.txt.

对于许多 Capacitor 插件，最快的 AGP 9 迁移方案是什么？

使用工作区范围的搜索替换命令，然后通过进行验证 git grep 并运行 bun run verify:android 在一些代表性插件中。

这只是 Capacitor 的问题吗？

不是。任何使用了已弃用的 ProGuard 基准引用的 Android 模块（应用或库）都可能遇到类似的 AGP 9 构建错误。这在插件生态系统中尤为常见，因为许多仓库都在共享旧的模板。

此次迁移有哪些相关的关键词？

如果你正在内部运维手册或支持页面中记录此内容，请包含以下术语：

AGP 9 构建错误
Android Gradle Plugin 9 缺少 ProGuard 文件
Capacitor 插件 Android 构建失败
proguard-android.txt 替换方案
proguard-android-optimize.txt 迁移

Android 开发者：应用构建概览
Android Gradle Plugin：发行说明
Android code 缩减： R8 与规则
Gradle 文档：构建工具基础
Capacitor 文档：官方文档
Capgo 文档：自动更新文档

总结

这个 AGP 9 问题很简单，但在多插件工作区里很容易被忽略。一旦你替换 proguard-android.txt 配合 proguard-android-optimize.txt 所有相关位置，Android build 就会重新变得可预测。

如果你使用 Capgo 插件，官方仓库已经应用了这次迁移，升级时能少踩坑。

继续阅读：Capacitor Plugin AGP 9 Build Error Fix

如果你正在使用 修复 Capacitor 插件 AGP 9 构建报错 规划 CI/CD 自动化，并将其与 Capgo CI/CD 用于 Capgo CI/CD 中的产品工作流， Capgo Native Build 用于 Capgo Native Builds 中的产品工作流， Capgo 集成用于 Capgo 集成中的产品工作流， CI/CD 集成了解 CI/CD 集成的实现细节，以及 GitHub Actions 集成有关 GitHub Actions 集成的实现细节。