Capacitor Plugin AGP 9 Build Error Fix

如果您 Capgo 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_KEEP_0__ Capgo __CAPGO_KEEP_0__在发布可靠性中的意义
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:

Gradle 作为构建系统。
Android Gradle 插件 (AGP) 作为 Android 特有的 Gradle 集成。
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__ 应用程序通常包括：
原生壳（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 友好的更新工作流程
CI/CD-friendly update workflows for Capacitor teams

即使有实时更新，原生构建的稳定性也是不可谈的。你仍然需要清洁的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 状态

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

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

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

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

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

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

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

如果在替换后仍然出现构建错误，请进行故障排除。

检查以下点:

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

SEO常见问题：AGP 9 Capacitor 插件构建错误

How do I fix __CAPGO_KEEP_0__ build errors in AGP 9? `proguard-android.txt` not found in 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.

What is the fastest AGP 9 migration path for many Capacitor plugins?

使用一个全局搜索替换命令，验证并运行 git grep and run bun run verify:android on 代表性插件。

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

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

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

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

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

Android Developers: 构建应用概览
Android Gradle Plugin: 发布说明
Android code 缩小: R8 和规则
Gradle 文档: 构建工具基础
Capacitor 文档: 官方文档
Capgo 文档: 自动更新文档

最终收获

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

如果你使用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 动作集成的实现细节

Capgo Capacitor 插件 AGP 9 构建错误修复