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

Si votre Capacitor plugin a commencé à échouer après la mise à niveau vers Android Gradle Plugin 9 (AGP 9), vous rencontrez probablement un problème de configuration Gradle mineur mais critique.

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

erreur de build du plugin Capacitor AGP 9
échec du build du plugin avec Android Gradle Plugin 9
proguard-android.txt introuvable
AGP 9 getDefaultProguardFile erreur
échec du build Android de Capacitor après la mise à niveau AGP

The short version:

proguard-android.txt n’est plus la baseline par défaut sûre à référencer dans les builds de plugins AGP 9.
Passez à proguard-android-optimize.txt.
Recompilez et vérifiez.

La version longue compte aussi, surtout si vous maintenez de nombreux plugins ou de grands workspaces Capacitor. Dans cet article, nous abordons :

Ce que sont Android et AGP dans la chaîne de build
Ce qu'est Capacitor et comment fonctionnent les builds de plugins
Qu'est-ce Capgo est et pourquoi cela compte pour la fiabilité des releases
Le changement exact d'AGP 9 qui casse les anciens templates de plugins
Une stratégie de migration sûre pour un dépôt ou plusieurs dépôts

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

Android est à la fois un système d’exploitation et un écosystème de build. Lorsque vous déployez une app ou un plugin Capacitor sur Android, votre projet passe par :

Gradle en tant que système de build.
Android Gradle Plugin (AGP) en tant qu’intégration Gradle spécifique à Android.
La chaîne d’outils Android SDK pour le packaging, la réduction, le lint et la génération .aar, .apk, ou .aab sorties.

Lorsque les versions d’AGP changent, certains paramètres par défaut et fichiers internes peuvent également évoluer. Une configuration de plugin qui fonctionnait avec AGP 8 peut échouer sur AGP 9 si elle pointe vers une base supprimée ou obsolète.

Qu'est-ce que Capacitor ?

Capacitor est un runtime multiplateforme qui permet de compiler des applications iOS/Android avec du code (TypeScript, JavaScript, HTML, CSS) tout en appelant des API natives.

Les applications Capacitor incluent généralement :

Une couche web (votre interface et votre logique métier)
Shells natifs (ios/, android/)
Plugins qui exposent des fonctionnalités natives à JavaScript

Chaque plugin possède sa propre configuration de build natif. Sur Android, cela signifie que chaque plugin inclut un android/build.gradle fichier qu'AGP doit analyser et compiler correctement.

Si les paramètres Gradle du plugin sont obsolètes, tout le build de l'app peut échouer, même si votre code web est correct.

Qu'est-ce que le Capgo ?

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

Mises à jour live pour les changements de bundle web
Écosystème de plugins et packages de fonctionnalités natives
Workflows de mise à jour compatibles CI/CD pour les équipes Capacitor

Même avec les live updates, la stabilité des builds natifs est non négociable. Il vous faut toujours des builds Android propres pour :

Les releases sur l’App Store / Play Store
Mises à niveau des plugins natifs
Les migrations de plateforme SDK
Onboarding de l’équipe et fiabilité de la CI

C’est pourquoi les correctifs de compatibilité AGP 9 sont importants : ils maintiennent votre couche de plugins fiable, pour que les pipelines de livraison restent prévisibles.

Pourquoi AGP 9 casse les anciennes configs de plugins

De nombreux modèles de plugins utilisaient historiquement :

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

Dans les configurations AGP 9, cette référence legacy de baseline peut ne plus fonctionner, car l’ancien fichier n’est plus forcément présent à l’emplacement attendu par les anciens templates/configs.

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

Contexte rapide : ProGuard, R8 et fichiers baseline

R8 est le shrinker/optimiseur moderne code dans les builds Android.
proguard-rules.pro sont vos règles de keep personnalisées pour le projet/plugin.
getDefaultProguardFile(...) injecte une baseline fournie par Android.

Lorsque vous référencez :

proguard-android.txt -> baseline legacy, minimale
proguard-android-optimize.txt -> baseline moderne optimisée (défaut recommandé dans les configurations actuelles)

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

Le correctif en une ligne

Update plugin and app module Gradle files:

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

Vérifiez au minimum :

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 une nouvelle configuration Gradle de plugin

Guide de migration pour un plugin

1. Trouver l'ancienne référence

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

2. La remplacer

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

3. Vérifier avec Bun

bun run verify:android

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

bun run verify

Mise à jour groupée de tous les repos de plugins

Si vous maintenez de nombreux dépôts de plugins dans un même workspace, 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"

Puis vérifiez qu’aucune source de plugin suivie n’utilise encore l’ancien fichier :

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

Aucune correspondance signifie que l’ancienne référence de baseline a disparu des fichiers de plugin suivis.

Statut du déploiement de Capgo

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

Les modules Android des plugins référencent désormais proguard-android-optimize.txt
Les apps Android d'exemple des plugins ont aussi été mises à jour
Les modèles de scaffolding de plugins ont été mis à jour pour que les nouveaux plugins soient compatibles AGP 9 par défaut

This prevents a common class of AGP 9 upgrade failures before they hit CI.

Pourquoi c’est important, même si votre build passe aujourd’hui

Vous ne verrez peut-être pas d’échecs immédiatement si :

Votre cache CI masque toujours le problème
Vous avez des versions AGP mélangées entre les projets
Seuls certains modules sont recompilés en dev locale

Mais tôt ou tard, des builds propres, de nouveaux environnements ou des runners mis à jour le révèlent. Faire la migration maintenant supprime une instabilité cachée.

Dépannage si les builds échouent encore après le remplacement

Vérifiez ces points :

Chaque module est patché. Regardez les modules de plugins, les modules d'app, les samples et les assets de template.
Il n'y a pas d'autre référence dans les scripts partagés. Cherchez dans les dépôts entiers (y compris les scripts Gradle personnalisés).
Les caches sont propres. Exécutez ./gradlew clean et relancez le build.
Les versions AGP / Gradle / JDK sont alignées.\nUtilisez les combinaisons supportées par la documentation Android pour votre version AGP.
La CI utilise les mêmes versions qu'en local. Figez les versions du JDK et du Gradle wrapper dans la CI pour éviter les dérives d'environnement.
Vous ne patchez pas seulement node_modules.\nCorrigez la source du plugin suivi, pas les répertoires de dépendances transitoires.

FAQ SEO : erreurs de build de plugin AGP 9 Capacitor

Comment corriger `proguard-android.txt` introuvable dans AGP 9 ?

Remplacer :

getDefaultProguardFile('proguard-android.txt')

Avec :

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

Puis lancez un rebuild propre.

Pourquoi le build de mon plugin Capacitor échoue-t-il après la mise à niveau vers Android Gradle Plugin 9 ?

La plupart des échecs proviennent d’une configuration Gradle obsolète dans le android/build.gradle fichier du plugin qui référence encore proguard-android.txt. Les projets AGP 9 doivent utiliser proguard-android-optimize.txt.

Quelle est la migration AGP 9 la plus rapide pour de nombreux plugins Capacitor ?

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

Est-ce un problème propre à Capacitor ?

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

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

Si vous documentez cela dans des runbooks internes ou des pages de support, incluez des termes comme :

Erreur de build AGP 9
Fichier ProGuard manquant pour Android Gradle Plugin 9
Échec du build Android d'un plugin Capacitor
proguard-android.txt remplacement
proguard-android-optimize.txt migration

Android Developers : Aperçu de la compilation de votre application
Android Gradle Plugin : Notes de version
Réduction de code Android code : R8 et règles
Documentation Gradle : Fondamentaux de l’outil de build
Documentation Capacitor : Documentation officielle
Docs Capgo : Docs de mise à jour automatique

Final takeaway

Ce problème AGP 9 est simple, mais on passe facilement à côté dans les workspaces multi-plugins. Une fois que vous aurez remplacé proguard-android.txt par proguard-android-optimize.txt partout où c'est nécessaire, les builds Android redeviendront prévisibles.

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

Continuer depuis Capacitor : correction de l'erreur de build AGP 9 du plugin

Si vous utilisez Correction de l'erreur de build AGP 9 du plugin Capacitor pour planifier l'automatisation CI/CD, et le connecter avec CI/CD Capgo pour le workflow produit dans le CI/CD de Capgo, Capgo Native Build pour le workflow produit dans les Native Builds de Capgo, Intégrations Capgo pour le workflow produit dans les intégrations de Capgo, Intégration CI/CD pour le détail d'implémentation dans l'intégration CI/CD, et Intégration GitHub Actions pour les détails d'implémentation de l'intégration GitHub Actions.