Capacitor Plugin AGP 9 Build Error Fix

如果您的 Capacitor Android Gradle Plugin 9 升级后，插件开始出现故障，很可能是由于 Gradle 配置问题引起的。

本文主要针对以下常见搜索意图：

Capacitor AGP 9 插件构建错误
AGP 9
proguard-android.txt Android Gradle Plugin 9
未找到 getDefaultProguardFile AGP 9
Capacitor Android build failed after AGP upgrade

__CAPGO_KEEP_0__ 升级 AGP 后的 Android 构建失败

proguard-android.txt 简而言之：
不再是 AGP 9 插件构建的安全默认基准。 proguard-android-optimize.txt.
切换到最新版本的 Android Gradle Plugin 9。

如果您维护了许多插件或大型Capacitor工作空间，那么更长的版本也很重要。本文将介绍以下内容：

Android 和 AGP 在构建链中的作用
Capacitor 是什么以及插件构建的工作原理
什么 Capgo 是什么以及为什么这对发布可靠性很重要
AGP 9 中确切的变化，破坏了旧的插件模板
一次仓库或多个仓库的安全迁移策略

在这个上下文中，Android 是什么

Android 是一个操作系统和一个构建生态系统。当您在 Android 上发布__CAPGO_KEEP_0__应用程序或插件时，项目将经过： is both an operating system and a build ecosystem. When you ship a Capacitor app or plugin on Android, your project goes through:

Android 和 AGP 在构建链中的作用作为构建系统。
Android Gradle 插件 (AGP) 作为 Android 特定的 Gradle 集成。
Android SDK 工具链用于打包、压缩、检查代码和生成 .aar, .apk, 或 .aab 输出。

当 AGP 版本发生变化时，某些默认值和内部文件也可能会发生变化。一个 AGP 8 配置的插件可能在 AGP 9 中失败，如果它指向一个已移除或已弃用的基线。

什么是 Capacitor?

Capacitor 是一个跨平台的运行时，让您可以使用 web code (TypeScript、JavaScript、HTML、CSS) 构建 iOS/Android 应用程序，同时仍然调用本机 API。

Capacitor 应用程序通常包括：

一个 web 层（您的 UI 和业务逻辑）
原生壳 (ios/, android/)
暴露原生功能给 JavaScript 的插件

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

如果插件的 Gradle 设置过时，整个应用程序的构建可能会失败，即使您的 web code 正确。

什么是 Capgo?

Capgo Capacitor 提供了围绕 Capacitor 交付和运营的工具：

实时更新针对 web 包的更改
插件生态系统和原生功能包
CI/CD 友好的更新工作流程，适用于 Capacitor 团队

即使有实时更新，原生构建稳定性也是不可谈的。你仍然需要清洁的Android构建文件：

App Store / Play Store发布
原生插件升级
平台SDK迁移
团队入职和CI可靠性

这就是为什么AGP 9兼容性修复很重要：它们让你的插件层可靠，所以交付管道保持可预测。

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

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

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

在AGP 9设置中，这个遗留基准参考可能会失败，因为旧文件不再在旧模板/配置期望的位置可用。

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

快速背景：ProGuard、R8和基线文件

R8 是 Android 构建中的现代 code 缩小/优化器。
proguard-rules.pro 是您的项目/插件自定义保留规则。
getDefaultProguardFile(...) 注入 Android 提供的基线文件。

当您引用：

proguard-android.txt -> legacy，最小基线
proguard-android-optimize.txt -> 当前设置中的推荐默认值（现代优化基线）

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

一行修复方案

更新插件和应用程序模块的 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 安全

这可以防止 AGP 9 升级失败的常见类别在 CI 之前

即使您的构建今天通过了，这也很重要

您可能不会立即看到失败的原因是

您的 CI 缓存仍然掩盖了问题
您在项目中混合使用了不同版本的 AGP
只有在本地开发中重建了某些模块

But finally, clean builds, new environments, or upgraded runners expose it. Doing the migration now removes hidden instability.

在替换后，如果构建仍然失败，请进行故障排除

检查以下点:

每个模块都已修补。查看插件模块、应用模块、示例和模板资产。
共享脚本中没有第二个引用。在整个仓库（包括自定义Gradle脚本）中搜索。
缓存已清除。运行 ./gradlew clean 并重建。
AGP / Gradle / JDK 版本保持一致。使用Android文档支持的AGP版本组合。
CI使用的版本与本地版本相同。在CI中将JDK和Gradle包装器版本固定，以避免环境漂移。
您不仅仅是修补 node_modules。修复跟踪的插件源，而不是临时依赖目录。

SEO FAQ: AGP 9 Capacitor 插件构建错误

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

替换：

getDefaultProguardFile('proguard-android.txt')

使用：

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

然后运行清洁重建。

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

大多数故障来自于插件中的遗留 Gradle 配置 android/build.gradle 文件仍然引用 proguard-android.txt. AGP 9 项目应使用 proguard-android-optimize.txt.

AGP 9 对多个 Capacitor 插件的最快迁移路径是什么？

使用一个工作区级别的查找和替换命令，然后使用 git grep 并运行 bun run verify:android 代表插件。

这是否仅仅是一个 Capacitor 问题?

不是。任何使用过时的 ProGuard 基线引用（app 或库）的 Android 模块（app 或库）都可能遇到类似的 AGP 9 构建错误，尤其是在插件生态系统中，因为许多仓库共享旧的模板。

此迁移中相关的关键词是什么?

如果您在内部运行手册或支持页面中记录此内容，请包含以下术语:

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

Android 开发者: 构建应用概览
Android Gradle 插件：更新日志
Android code 缩小： R8 和规则
Gradle 文档：构建工具基础
Capacitor 文档：官方文档
Capgo 文档：自动更新文档

最终收获

这个AGP 9问题很简单，但在多插件工作区中容易被忽略。一旦你在所有相关的地方替换 proguard-android.txt ，安卓构建就变得可预测了。 proguard-android-optimize.txt 如果你使用__CAPGO_KEEP_0__插件，这个迁移在官方仓库中已经应用了，所以你可以升级时少一些惊喜。

If you use Capgo plugins, this migration is already applied in official repositories so you can upgrade with fewer surprises.

Capacitor 插件 AGP 9 构建错误修复