Capacitor 插件 AGP 9 构建错误修复

如果您的 Capacitor 由于升级到 Android Gradle Plugin 9 (AGP 9) 后，插件开始出现故障，您很可能遇到了一个小但关键的 Gradle 配置问题。

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

Capacitor AGP 9 插件构建错误
AGP 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 上发布 __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:

__CAPGO_KEEP_0__ As __CAPGO_KEEP_0__ 系统。
Android Gradle 插件 (AGP) As 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-safe

这可以防止 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 所有相关地方，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 动作集成 GitHub 动作集成的实现细节