Capacitor プラグインの AGP 9 ビルドエラー修正

もしあなたの Capacitor Android Gradle Plugin 9 (AGP 9) へのアップグレード後にプラグインのビルドが失敗する場合、軽微ながらも重要な Gradle の設定問題に直面している可能性があります。

この記事では、特に以下のような検索意図に対応しています：

Capacitor plugin build エラー AGP 9
Android Gradle Plugin 9 plugin build 失敗
proguard-android.txt 見つかりません
AGP 9 getDefaultProguardFile エラー
Capacitor AGP アップグレード後に Android build 失敗

短く言うと：

proguard-android.txt は、AGP 9 のプラグインビルドで参照する安全なデフォルト基準ではなくなりました。
切り替え先： proguard-android-optimize.txt.
再ビルドして確認してください。

多くのプラグインや大規模な Capacitor ワークスペースを管理している場合、この詳細な理解は非常に重要です。この記事では以下について解説します：

ビルドチェーンにおける Android と AGP の役割
Capacitor とは何か、およびプラグインのビルドの仕組み
何が Capgo であり、なぜリリース時の信頼性に影響するのか
古いプラグインテンプレートを壊してしまう AGP 9 の具体的な変更点
単一または複数のリポジトリに対応する安全な移行戦略

この文脈における Android とは？

Android は、OS であると同時にビルドエコシステムでもあります。Android 用の Capacitor アプリやプラグインをリリースする際、プロジェクトは以下のプロセスを経ます：

Gradle ビルドシステムとして。
Android Gradle Plugin（AGP） Android固有のGradle統合として。
AndroidのSDKツールチェーンは、パッケージング、シュリンク、リンティング、および .aar, .apk、または .aab 出力生成を行います。

AGPのバージョンが変わると、デフォルト設定や内部ファイルも変更されることがあります。AGP 8で動作していたプラグイン設定でも、削除または非推奨になったベースラインを参照している場合、AGP 9では失敗する可能性があります。

Capacitorとは？

Capacitor ネイティブAPIを呼び出しつつ、Web code（TypeScript、JavaScript、HTML、CSS）でiOS/Androidアプリを構築できるクロスプラットフォームランタイムです。

Capacitorアプリには通常、以下が含まれます：

Webレイヤー（UIとビジネスロジック）
Native shell（ios/, android/)
JavaScriptにネイティブ機能を公開するプラグイン

各プラグインには独自の Native Build 設定があります。Android の場合、各プラグインには android/build.gradle AGP が正しく解析・コンパイルする必要があるファイルが含まれています。

プラグインの Gradle 設定が古いと、Web 側の code が正しくても、アプリ全体のビルドが失敗することがあります。

Capgo とは？

Capgo Capacitor の配信と運用に関するツールを提供します：

Live Updates Web bundle の変更用
プラグインエコシステムとネイティブ機能パッケージ
Capacitor チーム向けの CI/CD フレンドリーなアップデートワークフロー

Live Updatesを利用していても、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、およびbaselineファイルについて

R8 は、Androidビルドにおける最新の code shrinker/optimizer です。
proguard-rules.pro は、プロジェクトやプラグイン独自のkeepルールです。
getDefaultProguardFile(...) は、Androidが提供するbaselineを注入します。

以下の参照設定について：

proguard-android.txt -> レガシーな最小限のbaseline
proguard-android-optimize.txt -> モダンで最適化されたbaseline（現在の推奨設定）

AGP 9に対応するには、以下への切り替えが proguard-android-optimize.txt 現実的な解決策となります。

1行で完了する修正方法

プラグインとアプリモジュールの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

すべてのプラグインリポジトリを一括更新

1つのワークスペースで多くのプラグインリポジトリを管理している場合は、自動化しましょう：

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

No matches と表示された場合は、追跡対象のプラグインファイルから古いベースライン参照がなくなったことを意味します。

Capgo ロールアウト状況

すべての公式 Capgo Capacitor プラグインリポジトリとテンプレートで、この移行を完了しました：

プラグインのAndroidモジュールが参照するようになりました： proguard-android-optimize.txt
プラグインのサンプルAndroidアプリも更新されました
プラグインのスキャフォールディングテンプレートを更新し、新規プラグインがデフォルトでAGP 9セーフになるようにしました

これにより、AGP 9アップグレードでよくある失敗がCIに到達する前に防げます。

現在のビルドが通っていても、これが重要な理由

次のような場合は、失敗にすぐ気づかないことがあります：

CIのキャッシュがまだ問題を覆い隠している
プロジェクト間でAGPのバージョンが混在している
ローカル開発時に一部のモジュールのみを再ビルドしている

しかし、最終的にはクリーンビルドや新しい環境、アップグレードされたランナーによって問題が露呈します。今移行しておくことで、潜在的な不安定さを排除できます。

置換後もビルドが失敗する場合のトラブルシューティング

以下の点を確認してください：

すべてのモジュールにパッチが適用されているか。プラグインモジュール、アプリモジュール、サンプル、テンプレートアセットを確認してください。
共有スクリプト内に二重の参照がないか。リポジトリ全体（カスタムGradleスクリプトを含む）を検索してください。
キャッシュがクリアされているか。以下を実行してください： ./gradlew clean そして再ビルドします。
AGP / Gradle / JDK のバージョンが一致しているか。使用しているAGPバージョンに対して、Androidドキュメントがサポートしている組み合わせを使用してください。
CI環境がローカルと同じバージョンを使用しているか。環境の差異を防ぐため、CIではJDKとGradle wrapperのバージョンを固定してください。
パッチを当てているのは node_modulesだけではありません。一時的な依存関係のディレクトリではなく、追跡対象のプラグインソースを修正してください。

SEO FAQ: AGP 9によるCapacitorプラグインのビルドエラーの修正方法

修正方法 `proguard-android.txt` AGP 9で見つからない場合は？

以下を置き換え:

getDefaultProguardFile('proguard-android.txt')

次を使用:

getDefaultProguardFile('proguard-android-optimize.txt')

その後、クリーンビルドを実行してください。

Android Gradle Plugin 9にアップグレードした後、Capacitor プラグインのビルドが失敗するのはなぜですか？

ほとんどの失敗は、プラグイン内のレガシーなGradle設定が原因です。 android/build.gradle 依然として以下を参照しているファイル： proguard-android.txt。AGP 9プロジェクトでは次を使用します： proguard-android-optimize.txt.

多くの Capacitor プラグインで、AGP 9への最速の移行パスは何ですか？

ワークスペース全体の検索・置換コマンドを使い、次で検証します： git grep さらに実行： bun run verify:android 代表的なプラグインにおいて。

これは Capacitor 特有の問題ですか？

いいえ。非推奨のProGuard baseline参照を使用しているAndroidモジュール（アプリまたはライブラリ）であれば、同様の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 ドキュメント: Auto update ドキュメント

まとめ

このAGP 9に関する問題は単純ですが、複数のプラグインを扱うワークスペースでは見落としがちです。一度修正を適用すれば、 proguard-android.txt を使用して proguard-android-optimize.txt Androidのビルドは再び安定して動作するようになります。

Capgo のプラグインを使用している場合、公式リポジトリではすでにこの移行が完了しているため、よりスムーズにアップグレードできます。

Capacitor Plugin AGP 9 Build Error Fix の続きはこちら

使用している場合 Capacitor プラグインの AGP 9 ビルドエラー修正 CI/CD自動化を計画するには、次と連携してください Capgo での CI/CD 設定 Capgo CI/CDでのプロダクトワークフローについては、 Capgo Native Build Capgo Native Buildsでのプロダクトワークフローについては、 Capgo インテグレーション Capgo インテグレーションでのプロダクトワークフロー向けに、 CI/CD 連携 CI/CD Integrationの実装詳細については、 GitHub Actions 連携 GitHub Actions Integrationの実装詳細については。