Capacitor 插件 AGP 9 构建错误修复

如果您的 Capacitor 插件在升级到 Android Gradle Plugin 9 (AGP 9) 后开始失败，您很可能遇到了 Gradle 配置问题中的一个小但关键问题。

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

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

简要版：

proguard-android.txt 不再是 AGP 9 插件构建的安全默认基准。
切换到 proguard-android-optimize.txt.
重新构建并验证。

长版本也很重要，尤其是如果您维护了许多插件或大型 Capacitor 工作空间。在本文中，我们将介绍：

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

在这个上下文中 Android 是什么

Android 既是一个操作系统又是一个构建生态系统。当你在 Android 上发布一个 Capacitor 应用程序或插件时，项目将通过：

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

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

什么是 Capacitor？

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

Capacitor 应用程序通常包括：

一个 web 层（您的 UI 和业务逻辑）
Native shells（ios/, android/)
暴露 native 特性给 JavaScript 的插件

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

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

什么是 Capgo?

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

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

即使有实时更新，native build 的稳定性也是不可谈判的。您仍然需要清洁的 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 rollout 状态

We完成了此迁移在所有官方Capgo Capacitor插件仓库和模板中:

插件Android模块现在引用 proguard-android-optimize.txt
插件示例Android应用程序也已更新
插件骨架模板已更新，以便新插件默认为AGP 9安全

这防止了AGP 9升级失败的常见类别，避免它们在CI中出现

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

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

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

但最终，清洁的构建、新的环境或升级的运行器会暴露它。现在进行迁移可以移除隐含的不稳定性

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

检查这些点：

每个模块都被修补。查看插件模块、应用模块、示例和模板资产。
共享脚本中没有第二个引用。搜索整个仓库（包括自定义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 基线参考的 Android 模块 (应用或库) 都可能遇到类似的 AGP 9 构建错误。尤其是在插件生态系统中，因为许多仓库共享老的模板。

__CAPGO_KEEP_0__ 插件 Android 构建失败

如果您在内部运行手册或支持页面中记录此迁移，请包含以下关键词:

AGP 9 构建错误
Android Gradle Plugin 9 ProGuard 文件丢失
Capacitor plugin Android build failed
proguard-android.txt 迁移
proguard-android-optimize.txt 相关链接

Android Gradle Plugin: Android Gradle Plugin 9 ProGuard 文件丢失
Android Gradle Plugin 9 ProGuard 文件丢失 Release notes
Android code 缩小: R8 和规则
Gradle 文档: 构建工具基础
Capacitor 文档: 官方文档
Capgo 文档: 自动更新文档

最后的收获

这个 AGP 9 问题很简单，但在多插件工作区中很容易忽略。一旦您替换 proguard-android.txt with proguard-android-optimize.txt 在所有相关的 Android 构建中，变得可预测了。

如果您使用 Capgo 插件，则此迁移已在官方仓库中应用，因此您可以升级时会有更少的惊喜。

从 Capacitor 插件 AGP 9 构建错误修复继续

如果您正在使用 Capacitor 插件 AGP 9 构建错误修复 来规划 CI/CD 自动化，连接它与 Capgo CI/CD 为产品工作流程在 Capgo CI/CD 中 Capgo 原生构建为产品工作流程在 Capgo 原生构建中 Capgo 集成为产品工作流程在 Capgo 集成中, CI/CD 集成 CI/CD 集成的实现细节 GitHub Actions 集成 GitHub Actions 集成的实现细节