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 Android 构建在 AGP 升级后失败

简短版本:

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

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

Android 和 AGP 在构建链中的作用
Capacitor 是什么以及插件构建的工作原理
什么 Capgo 在 Capgo 提交 PR 的过程中，__CAPGO_KEEP_0__ 是什么以及插件构建的工作原理
__CAPGO_KEEP_0__ 是什么以及为什么这对发布可靠性至关重要
破坏旧插件模板的 AGP 9 精确更改

针对一个仓库或多个仓库的安全迁移策略

Android Android 是一个操作系统和一个构建生态系统。当您在 Android 上发布一个 Capacitor 应用程序或插件时，项目将通过以下步骤进行:

Gradle 作为构建系统 Gradle
Android Gradle Plugin (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__ 应用程序通常包括:
一个 web 层（您的 UI 和业务逻辑）ios/, android/)
expose native features to JavaScript

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

什么是code?

Capgo

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

web包装更改插件生态系统和native特性包
CI/CD友好的__CAPGO_KEEP_0__更新工作流
CI/CD-friendly update workflows for Capacitor teams

Plugins that expose native features to JavaScript

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版本
只有在本地开发中重建了某些模块

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

解决Capacitor插件构建错误的方法

检查以下点:

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

SEO常见问题：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.

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

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

是否这是一个Capacitor问题?

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

哪些关键词与此迁移相关?

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

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

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操作集成中的实现细节