Capacitor Correction de l'erreur de build du plugin AGP 9

Si votre Capacitor Le plugin a cessé de fonctionner après avoir mis à niveau le plugin Android Gradle vers la version 9 (AGP 9), vous risquez probablement de rencontrer une petite mais critique erreur de configuration de Gradle.

Cet article cible spécifiquement les intentions de recherche courantes comme :

Capacitor erreur de construction du plugin AGP 9
Le plugin de construction d'AGP 9 a échoué
proguard-android.txt non trouvé
AGP 9 getDefaultProguardFile erreur
Capacitor échec de la construction Android après mise à niveau d'AGP

La version courte :

proguard-android.txt n'est plus la référence de base sécurisée à utiliser dans les builds de plugins AGP 9.
Passer à proguard-android-optimize.txt.
Refaire et vérifier.

La version plus longue compte également, surtout si vous gérez de nombreux plugins ou de grands Capacitor environnements de travail.

Qu'est-ce qu'Android et AGP sont dans la chaîne de construction
Qu'est-ce que Capacitor est et comment fonctionnent les builds des plugins
Qu'est-ce que Capgo est et pourquoi cela compte pour la fiabilité des releases
Le changement exact d'AGP 9 qui brise les anciens modèles de template de plugin
Une stratégie de migration sûre pour un référentiel ou plusieurs référentiels

Qu'est-ce qu'Android dans ce contexte?

Android est à la fois un système d'exploitation et un écosystème de construction. Lorsque vous envoyez une application ou un plugin Capacitor sur Android, votre projet passe par :

Gradle As le système de construction.
Plugin Android Gradle (AGP) As une intégration Gradle spécifique à Android.
Le kit de développement Android SDK pour l'emballage, la réduction, la vérification de l'intégrité et la production de .aar, .apk, ou .aab Les sorties.

Lorsque les versions de AGP changent, certaines valeurs par défaut et des fichiers internes peuvent changer également. Une configuration de plugin qui fonctionnait pour AGP 8 peut échouer sur AGP 9 si elle pointe vers une ligne de base supprimée ou obsolète.

Qu'est-ce que Capacitor ?

Capacitor est un runtime cross-plateforme qui vous permet de construire des applications iOS/Android avec des code web (TypeScript, JavaScript, HTML, CSS) tout en appelant des API natives.

Les applications Capacitor comprennent généralement :

Une couche web (votre interface utilisateur et votre logique métier)
Boîtes natives (ios/, android/)
Plugins qui exposent des fonctionnalités natives au JavaScript

Chaque plugin a sa propre configuration de construction native. Sur Android, cela signifie que chaque plugin inclut un android/build.gradle fichier que AGP doit analyser et compiler correctement.

Si les paramètres Gradle des plugins sont obsolètes, la construction de l'application entière peut échouer, même si votre paquet web code est correct.

Qu'est-ce que Capgo ?

Capgo fournit des outils autour de la livraison et de l'exploitation de Capacitor :

Mises à jour en temps réel pour les modifications du paquet web
Écosystème de plugins et de packages de fonctionnalités natives
Flux de travail d'actualisation CI/CD pour les équipes de Capacitor

Même avec les mises à jour en temps réel, la stabilité des builds natifs n'est pas négociable. Vous avez toujours besoin de builds Android propres pour :

Sorties sur l'App Store / Play Store
Mises à jour de plugins natifs
Migrations de plateforme SDK
Formation de l'équipe et fiabilité de CI

C'est pourquoi les correctifs de compatibilité AGP 9 sont importants : ils gardent votre couche de plugin fiable afin que les pipelines de livraison restent prévisibles.

Pourquoi AGP 9 brise les anciens paramètres de plugin

Beaucoup de modèles de plugin ont historiquement utilisé :

proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'

Dans les configurations AGP 9, cette référence de base de l'ancien système peut échouer car le fichier ancien n'est plus garanti dans la localisation attendue par les anciens modèles/configurations.

Les symptômes typiques incluent des erreurs Gradle pendant les phases de assemble, lint, ou build phases, souvent pointant vers des ressources de ProGuard manquantes ou des références de fichiers par défaut invalides.

Contexte rapide : ProGuard, R8 et fichiers de base

R8 est le compresseur/optimiseur moderne de code dans les builds Android.
proguard-rules.pro sont vos règles de conservation personnalisées pour le projet/plugin.
getDefaultProguardFile(...) injecte un fichier de base fourni par Android.

Lorsque vous référez :

proguard-android.txt -> fichier de base legacy, minimal
proguard-android-optimize.txt -> fichier de base optimisé moderne (recommandé par défaut dans les configurations actuelles)

Pour la compatibilité avec AGP 9, passer à proguard-android-optimize.txt est la solution pratique.

La solution de correction en une ligne

Mettez à jour les fichiers Gradle du plugin et du module d'application :

proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'

At minimum, vérifiez :

android/build.gradle dans chaque plugin
example-app/android/app/build.gradle dans les dépôts de plugins
Tous les fichiers de générateur/modèle qui créent de nouvelles configurations Gradle de plugin

Guide de migration pour un plugin

1. Trouvez la référence ancienne

rg -n "proguard-android\\.txt" android example-app

2. Remplacez-la

perl -pi -e "s/proguard-android\\.txt/proguard-android-optimize.txt/g" \
  android/build.gradle example-app/android/app/build.gradle

3. Vérifiez avec Bun

bun run verify:android

Si votre plugin dispose de scripts de vérification complets, exécutez :

bun run verify

Mise à jour de masse de tous les dépôts de plugins

Si vous gérez de nombreux dépôts de plugins dans un même espace de travail, automatisez-le :

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"

Vérifiez ensuite que aucune source de plugin suivie n'utilise toujours le fichier ancien :

for d in capacitor-*; do
  [ -d "$d/.git" ] || continue
  git -C "$d" grep -n "proguard-android\\.txt" -- || true
done

No matches signifie que l'ancienne référence de base a disparu des fichiers de plugin suivis.

État de déploiement de Capgo

Nous avons effectué cette migration dans tous les dépôtoires et modèles de plugin officiels Capgo Capacitor :

Les modules de plugin Android référencent maintenant proguard-android-optimize.txt
Les applications Android d'exemple de plugin ont également été mises à jour
Les modèles de création de plugin ont été mis à jour afin que les nouveaux plugins soient par défaut AGP 9-sûrs

Cela empêche une classe courante de problèmes d'amélioration AGP 9 avant qu'ils ne rencontrent la CI.

Pourquoi cela est important même si votre build passe aujourd'hui

Vous ne voyez pas les erreurs immédiatement si :

Votre cache CI masque toujours l'issue
Vous avez des versions AGP mixtes dans les projets
Seuls certains modules sont reconstruits en développement local

But finalement, les builds propres, les environnements nouveaux ou les exécuteurs mis à jour révèlent cela. Effectuer la migration maintenant supprime l'instabilité cachée.

Résolution des problèmes si les builds échouent encore après la remplacement

Vérifiez ces points :

Chaque module est patché. Regardez les modules de plugin, les modules d'application, les exemples et les actifs de modèle.
Il n'y a pas de deuxième référence dans les scripts partagés. Recherchez les dépôtoires entiers (y compris les scripts Gradle personnalisés).
Les caches sont propres. Exécutez ./gradlew clean et reconstruisez.
Les versions AGP / Gradle / JDK sont alignées. Utilisez les combinaisons supportées par la documentation Android pour votre version AGP.
Le CI utilise les mêmes versions que locales. Fixez les versions JDK et wrapper Gradle dans le CI pour éviter la dérive de l'environnement.
Vous ne patchez pas uniquement node_modules. Fixez la source de plugin suivie, pas les répertoires de dépendances transitoires.

FAQ SEO : erreurs de build plugin AGP 9 Capacitor

Comment puis-je résoudre `proguard-android.txt` n'a pas été trouvé dans AGP 9 ?

Remplacez :

getDefaultProguardFile('proguard-android.txt')

Par :

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

Effectuez ensuite une reconstruction propre.

Pourquoi ma plugin Capacitor de construction échoue-t-il après avoir mis à niveau vers Android Gradle Plugin 9 ?

La plupart des échecs proviennent de la configuration Gradle legacy dans le plugin android/build.gradle fichiers qui référencent toujours proguard-android.txt. Les projets AGP 9 doivent utiliser proguard-android-optimize.txt.

Quel est le chemin de migration le plus rapide AGP 9 pour de nombreux plugins Capacitor ?

Utilisez une commande de recherche et de remplacement à l'échelle de l'ensemble de l'espace de travail, puis validez avec git grep et exécutez bun run verify:android On plugins représentatifs.

Est-ce que cela ne concerne que ce problème Capacitor?

Non. Toute module Android (application ou bibliothèque) utilisant des références de ligne de base ProGuard obsolètes peut rencontrer des erreurs de build similaires AGP 9. Cela est particulièrement visible dans les écosystèmes de plugins car de nombreux dépôts partagent des modèles anciens.

Quels mots-clés sont pertinents pour cette migration?

Si vous documentez cela dans des livres de procédures internes ou des pages de support, incluez des termes comme :

Erreur de build AGP 9
Fichier ProGuard manquant du plugin Android Gradle 9
Échec de la construction du plugin Android Capacitor
proguard-android.txt remplacement
proguard-android-optimize.txt migration

Developpeurs Android : Résumé de votre application
Android Gradle Plugin : Notes de version
Android code réduction : R8 et règles
Documentation Gradle : Fondamentaux de l'outil de construction
Capacitor documentation : Documentation officielle
Capgo documentation : Documentation de mise à jour automatique

Conclusion finale

Cette erreur AGP 9 est simple, mais elle est facile à manquer dans les environnements de travail multi-plugin. proguard-android.txt Une fois que vous remplacez proguard-android-optimize.txt par

If you use Capgo plugins, this migration is already applied in official repositories so you can upgrade with fewer surprises.

Si vous utilisez des plugins Capacitor, cette migration est déjà appliquée dans les dépôts officiels, vous pouvez donc mettre à niveau avec moins de surprises.

Continuez à partir de la correction d'erreur de build AGP 9 du plugin __CAPGO_KEEP_0__ Capacitor Plugin AGP 9 Build Error Fix la correction d'erreur de build AGP 9 du plugin __CAPGO_KEEP_0__ Capgo CI/CD le workflow de produit dans Capgo CI/CD, le workflow de produit dans Capgo Native Builds, le workflow de produit dans Capgo Native Builds, Intégrations Capgo pour le flux de travail du produit dans les Intégrations Capgo, Intégration CI/CD pour le détail d'implémentation dans l'Intégration CI/CD, et Intégration d'actions GitHub pour le détail d'implémentation dans l'Intégration d'actions GitHub.

Capacitor Plugin AGP 9 Build Error Fix