Capacitor Plugin AGP 9 Build Error Fix

如果您的 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.
• 重新构建并验证。

The longer version matters too, especially if you maintain many plugins or large Capacitor workspaces. In this article we cover:

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

在本文中，什么是 Android

Android is both an operating system and a build ecosystem. When you ship a Capacitor app or plugin on Android, your project goes through:

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

当 AGP 版本发生变化时，某些默认设置和内部文件也可能会发生变化。一个针对 AGP 8 的插件配置在 AGP 9 上可能会失败，因为它指向了一个已移除或被弃用的基线。

什么是 Capacitor?

Capacitor is a cross-platform runtime that lets you build iOS/Android apps with web code (TypeScript, JavaScript, HTML, CSS) while still calling native APIs.

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

• __CAPGO_KEEP_0__ 应用程序通常包括：
• 原生壳（Native shells (ios/, android/)
• 暴露原生功能给 JavaScript 的插件

每个插件都有自己的原生构建配置。 在 Android 上，这意味着每个插件都包含一个 AGP 必须解析和编译正确的文件。 android/build.gradle 如果插件的 Gradle 设置过时，整个应用程序的构建可能会失败，即使您的 web __CAPGO_KEEP_0__ 正确。

什么是 code?

Capgo

提供围绕 Capgo 交付和运营的工具: provides tools around Capacitor delivery and operations:

• 适用于 web 包装更改的 插件生态系统和原生功能包
• CI/CD 友好的更新工作流程，适用于 __CAPGO_KEEP_0__ 团队
• 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 -> modern优化基线（当前设置中的推荐默认值）

为了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 状态

我们完成了此迁移的所有官方Capgo Capacitor插件仓库和模板:

• 插件Android模块现在引用 proguard-android-optimize.txt
• 插件示例Android应用程序也已更新
• 插件骨架模板已更新，因此新插件默认情况下是AGP 9安全的

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

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

您可能不会立即看到失败的情况:

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

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

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

检查以下点:

1. 每个模块都已修补。 查看插件模块、应用模块、示例和模板资产。

2. 共享脚本中没有第二个引用。 在整个仓库（包括自定义Gradle脚本）中搜索。

3. 缓存已清洁。 运行 并重新构建。 ./gradlew clean AGP / Gradle / JDK版本已对齐。 使用Android文档支持的AGP版本组合。

4. CI使用的版本与本地版本相同。 在CI中将JDK和Gradle包装器版本固定以避免环境漂移。

5. 您不仅仅是修补 。 修复跟踪的插件源，而不是临时依赖目录。

6. SEO常见问题：AGP 9 __CAPGO_KEEP_0__ 插件构建错误 node_modulesTroubleshooting if builds still fail after the replacement

Check these points: Every module is patched. Look at plugin modules, app modules, samples, and template assets. There is no second reference in shared scripts. Search entire repositories (including custom Gradle scripts). Caches are clean. Run and rebuild. AGP / Gradle / JDK versions are aligned. Use combinations supported by Android documentation for your AGP version. CI uses the same versions as local. Pin JDK and Gradle wrapper versions in CI to avoid environment drift. You are not patching only . Fix tracked plugin source, not transient dependency directories. SEO FAQ: AGP 9 Capacitor plugin build errors

如何修复 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.txtAGP 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 Plugin: 发布说明
• Android code 缩小: R8 和规则
• Gradle 文档: 构建工具基础
• Capacitor 文档: 官方文档
• Capgo 文档: 自动更新文档

最终收获

这是一种简单的AGP 9问题，但在多插件工作区中容易被忽略。 一旦您将所有相关的__CAPGO_KEEP_0__替换为 proguard-android.txt 在所有相关的地方 proguard-android-optimize.txt Android构建就变得可预测了。

如果您使用Capgo插件，这个迁移已经在官方仓库中应用过了，所以您可以升级时会有更少的惊喜。

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

如果您正在使用__CAPGO_KEEP_0__插件AGP 9构建错误修复 Capacitor Plugin AGP 9 Build Error Fix __CAPGO_KEEP_0__ CI/CD 为产品工作流程在Capgo CI/CD for the product workflow in Capgo CI/CD, Capgo Native Builds 为产品工作流程在Capgo Native Builds, Capgo 集成 为产品工作流程在 Capgo 集成中 CI/CD 集成 为 CI/CD 集成的实现细节 GitHub 动作集成 为 GitHub 动作集成的实现细节