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

Si votre Capacitor contexte : Mises à jour en direct de la page de produits. Rôle : Titre de section ou de page. Vu dans : page live-update.astro. Conservez les termes de produit/marque et les termes de développeur exactement. Clé de message `live_update_platform_capacitor_title` (Titre de la plateforme d'actualisation en direct Capacitor).

Vous rencontrez probablement une petite mais critique erreur de configuration Gradle après avoir mis à jour le plugin Android Gradle 9 (AGP 9).

Capacitor plugin build error AGP 9
__CAPGO_KEEP_0__ erreur de build du plugin AGP 9
proguard-android.txt Échec de la build du plugin AGP 9 Android
non trouvé getDefaultProguardFile AGP 9
erreur de build du plugin AGP 9 : Capacitor

La version courte :

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

La version plus longue compte aussi, surtout si vous gérez de nombreux plugins ou de grands espaces de travail Capacitor. Dans cet article, nous couvrons :

Qu'est-ce qu'Android et AGP dans la chaîne de build
Qu'est-ce que Capacitor et comment fonctionnent les builds de plugins
Qu'est-ce que Capgo context : fragment de texte HTML d'une chaîne de Capgo UI plus longue (clé parente `submitting_a_pr_to_capgo`). Page/zone : site Web de marketing Capgo. Rôle : phrase de site Web. Vu dans : page contributing.astro. Conservez exactement les termes de produit/branche et les termes de développeur Capgo.
est et pourquoi cela compte pour la fiabilité des releases
Le changement exact AGP 9 qui brise les anciens modèles de template de plugin

Qu'est-ce que l'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 comme système de construction.
Android Gradle Plugin (AGP) comme intégration Gradle spécifique à Android.
Le kit d'outils Android SDK pour la mise en boîte, la réduction, la vérification de l'intégrité et la production de .aar, .apk, ou .aab sorties.

Lorsque les versions d'AGP changent, certaines valeurs par défaut et des fichiers internes peuvent changer également. Une configuration de plugin qui fonctionnait pour AGP 8 peut ne pas fonctionner avec 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 créer des applications iOS/Android avec le web code (TypeScript, JavaScript, HTML, CSS) tout en appelant des APIs natives.

Capacitor

Une couche web (votre interface utilisateur et logique métier)
Des coques natives (ios/, android/)
Des plugins qui exposent des fonctionnalités natives au JavaScript

Chaque plugin a sa propre configuration de build native. Sur Android, cela signifie que chaque plugin inclut un android/build.gradle Si les paramètres Gradle des plugins sont obsolètes, la construction de l'application entière peut échouer, même lorsque votre web __CAPGO_KEEP_0__ est correct.

Qu'est-ce que code?

Capgo

propose des outils autour de la livraison et de l'exploitation de Capgo : provides tools around Capacitor delivery and operations:

Actualisations en direct pour les modifications du paquet web
Écosystème de plugins et packages de fonctionnalités natives
Flux de mise à jour compatibles CI/CD pour les Capacitor équipes

Même avec des actualisations en direct, la stabilité de la construction native n'est pas négociable. Vous avez toujours besoin de constructions Android propres pour :

Sorties de l'App Store / Play Store
Mises à niveau de plugins natives
Migrations de la plateforme SDK
Intégration 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 config de plugin

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

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

In les configurations AGP 9, cette référence de base légère peut échouer car le fichier ancien n'est plus garanti dans l'emplacement attendu par les anciens modèles/configs.

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

Contexte rapide : ProGuard, R8 et les fichiers de base

R8 is the modern code shrinker/optimizer in Android builds.
proguard-rules.pro est vos règles de conservation personnalisées pour le projet/plugin.
getDefaultProguardFile(...) injecte une base Android fournie.

Lorsque vous référez :

proguard-android.txt -> base de base légère (ancienne, minimale)
proguard-android-optimize.txt -> base de base optimisée moderne (défaut recommandé dans les configurations actuelles)

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

La solution de fix rapide

Mettez à jour les fichiers Gradle des modules de plugin et d'application :

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

Au minimum, vérifiez :

android/build.gradle dans chaque plugin
example-app/android/app/build.gradle dans les dépôts de plugin
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 complète, exécutez :

bun run verify

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

Si vous gérez de nombreux dépôts de plugin dans un même espace de travail, automatissez-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

Aucun match signifie que la référence de base ancienne est disparue des fichiers de plugin suivis.

Capgo statut de déploiement

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

Les modules Android des plugins se réfèrent désormais à proguard-android-optimize.txt
Les exemples d'applications Android des plugins ont également été mis à jour
Les modèles de création de plugins ont été mis à jour afin que les nouveaux plugins soient par défaut sécurisés par rapport à AGP 9

Cela empêche une classe courante de pannes d'amélioration de l'AGP 9 avant qu'elles ne rencontrent la CI.

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

Vous ne voyez peut-être 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

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

Résoudre les problèmes si les builds échouent encore après le remplacement

Vérifiez ces points :

Tous les modules sont patchés. 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ôts entiers (y compris les scripts Gradle personnalisés).
Les caches sont propres. Exécutez et reconstruirez. ./gradlew clean Les versions AGP / Gradle / JDK sont alignées. Utilisez les combinaisons supportées par la documentation Android pour votre version AGP.
AGP / Gradle / JDK versions are aligned. Use combinations supported by Android documentation for your AGP version.
Les versions utilisées par la CI sont les mêmes que celles locales. Fixez les versions de JDK et du wrapper Gradle dans la CI pour éviter les dérives d'environnement.
Vous ne corrigez que les dépendances suivies, pas les répertoires de dépendances transitoires. node_modulesFAQ SEO : erreurs de construction de plugin AGP 9 __CAPGO_KEEP_0__

SEO FAQ: AGP 9 Capacitor plugin build errors

n'est pas trouvé dans AGP 9 ? `proguard-android.txt` Remplacez :

Par :

getDefaultProguardFile('proguard-android.txt')

Effectuez ensuite une reconstruction propre.

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

Pourquoi ma construction de plugin __CAPGO_KEEP_0__ échoue après avoir mis à niveau le plugin Gradle Android 9 ?

Why does my Capacitor plugin build fail after upgrading to Android Gradle Plugin 9?

les versions de Gradle antérieures à 7.3.3. android/build.gradle Les plugins qui utilisent des versions de Gradle inférieures à 7.3.3 ne sont pas pris en charge dans AGP 9. proguard-android.txt. Projets AGP 9 doivent utiliser proguard-android-optimize.txt.

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

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

Est-ce que cela ne concerne que des Capacitor problèmes ?

Non. Toute module Android (application ou bibliothèque) utilisant des références de ProGuard dépréciées peut rencontrer des erreurs de build AGP 9 similaires. 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 run ou des pages de support, incluez des termes comme :

Erreur de build AGP 9
Fichier ProGuard Android Gradle Plugin 9 manquant
Capacitor plugin Android build échoué
proguard-android.txt remplacement
proguard-android-optimize.txt migration

Android Developers : Vue d'ensemble de la construction 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 docs : Documentation officielle
Capgo docs : Documentation d'actualisation automatique

Conclusion finale

Cet problème AGP 9 est simple, mais il est facile à manquer dans les environnements de travail multi-plugin. Une fois que vous remplacez proguard-android.txt avec proguard-android-optimize.txt partout où cela est pertinent, les builds Android deviennent prévisibles à nouveau.

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

Continuez de Capacitor Plugin AGP 9 Build Error Fix

Si vous utilisez __CAPGO_KEEP_0__ Plugin AGP 9 Build Error Fix Capacitor Plugin AGP 9 Build Error Fix __CAPGO_KEEP_0__ Capgo CI/CD pour le flux de travail du produit dans Capgo CI/CD Capgo Builds natifs pour le flux de travail du produit dans Capgo Builds natifs Capgo Intégrations pour le flux de travail du produit dans Capgo Intégrations Intégration CI/CD pour les détails d'implémentation dans Intégration CI/CD, et GitHub Actions d'intégration pour les détails d'implémentation dans GitHub Actions d'intégration

Capacitor Plugin Erreur de construction AGP 9 Correction