Correzione errore build AGP 9 del plugin Capacitor

Se la tua Capacitor Se il plugin ha iniziato a fallire dopo l'aggiornamento ad Android Gradle Plugin 9 (AGP 9), probabilmente ti sei imbattuto in un problema di configurazione Gradle, piccolo ma critico.

Questo post è mirato specificamente a ricerche comuni come:

errore build plugin Capacitor AGP 9
Errore durante la build del plugin con Android Gradle Plugin 9
proguard-android.txt non trovato
AGP 9 getDefaultProguardFile errore
build Android Capacitor fallita dopo upgrade AGP

The short version:

proguard-android.txt non è più il baseline predefinito sicuro da usare nelle build dei plugin con AGP 9.
Passa a proguard-android-optimize.txt.
Ricostruisci e verifica.

Anche la versione più lunga è importante, specialmente se gestisci molti plugin o grandi workspace Capacitor. In questo articolo vedremo:

Il ruolo di Android e AGP nella build chain
Cos'è Capacitor e come funzionano le build dei plugin
Cos'è Capgo e perché è fondamentale per l'affidabilità del rilascio
Il cambiamento esatto di AGP 9 che rompe i vecchi template dei plugin
Una strategia di migrazione sicura per uno o più repo

Cos'è Android in questo contesto?

Android è sia un sistema operativo che un ecosistema di build. Quando pubblichi un'app o un plugin Capacitor su Android, il tuo progetto passa attraverso:

Gradle come sistema di build.
Android Gradle Plugin (AGP) come integrazione Gradle specifica per Android.
La toolchain Android SDK per il packaging, lo shrinking, il linting e la produzione di .aar, .apk, o .aab output.

Quando le versioni di AGP cambiano, possono cambiare anche alcuni default e file interni. Una configurazione di un plugin che funzionava con AGP 8 potrebbe fallire con AGP 9 se punta a una baseline rimossa o deprecata.

Cos'è Capacitor?

Capacitor è un runtime cross-platform che ti permette di buildare app iOS/Android con code web (TypeScript, JavaScript, HTML, CSS) chiamando comunque API native.

Le app Capacitor solitamente includono:

Un layer web (la tua UI e la business logic)
Shell native (ios/, android/)
Plugin che espongono funzionalità native a JavaScript

Ogni plugin ha la propria configurazione di Native Build. Su Android, questo significa che ogni plugin include un android/build.gradle file che AGP deve analizzare e compilare correttamente.

Se le impostazioni Gradle del plugin sono obsolete, l'intero build dell'app può fallire, anche se il tuo web code è corretto.

Cos'è Capgo?

Capgo fornisce strumenti per il delivery e le operazioni di Capacitor:

Live Update per modifiche al web bundle
Ecosistema di plugin e pacchetti di funzionalità native
Workflow di aggiornamento CI/CD-friendly per team Capacitor

Anche con i live updates, la stabilità del Native Build è fondamentale. Ti servono build Android pulite per:

Rilasci su App Store / Play Store
Aggiornamenti dei plugin nativi
Migrazioni della piattaforma SDK
Onboarding del team e affidabilità della CI

Ecco perché i fix per la compatibilità con AGP 9 sono cruciali: mantengono affidabile il layer dei plugin, garantendo pipeline di delivery prevedibili.

Perché AGP 9 rompe le vecchie configurazioni dei plugin

Storicamente, molti template dei plugin usavano:

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

In configurazioni AGP 9, questo riferimento legacy può fallire perché il vecchio file non è più garantito nella posizione prevista dai vecchi template o config.

I sintomi tipici includono errori Gradle durante le assemble, lint, o build fasi, spesso indicando risorse ProGuard baseline mancanti o riferimenti a file di default non validi.

Breve introduzione: ProGuard, R8 e baseline files

R8 è il moderno code shrinker/optimizer per build Android.
proguard-rules.pro sono le regole personalizzate del tuo progetto/plugin.
getDefaultProguardFile(...) inietta una baseline fornita da Android.

Quando si fa riferimento a:

proguard-android.txt -> baseline legacy e minimale
proguard-android-optimize.txt -> baseline moderna ottimizzata (default consigliato negli setup attuali)

Per la compatibilità con AGP 9, passare a proguard-android-optimize.txt è la soluzione pratica.

La fix in una riga

Aggiorna i file Gradle del plugin e del modulo app:

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

Almeno, controlla:

android/build.gradle in ogni plugin
example-app/android/app/build.gradle nei repo dei plugin
Eventuali file generator/template che creano la nuova config Gradle del plugin

Guida alla migrazione di un plugin

1. Trova il vecchio riferimento

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

2. Sostituiscilo

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

3. Verifica con Bun

bun run verify:android

Se il tuo plugin ha script di verifica completi, esegui:

bun run verify

Aggiornamento massivo di tutti i repo dei plugin

Se gestisci molti repository di plugin in un unico workspace, automatizza:

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"

Poi valida che nessun codice sorgente dei plugin tracciati usi ancora il vecchio file:

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

«No matches» significa che il vecchio riferimento baseline è sparito dai file dei plugin tracciati.

stato del rollout di Capgo

Abbiamo completato questa migrazione in tutti i repository e i template ufficiali dei plugin Capgo Capacitor:

Ora i moduli Android dei plugin fanno riferimento a proguard-android-optimize.txt
Anche le app Android di esempio dei plugin sono state aggiornate
I template per lo scaffolding dei plugin sono stati aggiornati: i nuovi plugin sono AGP 9-safe di default

Questo evita una categoria comune di errori di upgrade ad AGP 9 prima che arrivino in CI.

Perché è importante anche se oggi la tua build passa

Potresti non vedere subito gli errori se:

La cache della tua CI maschera ancora il problema
Hai versioni AGP miste tra i progetti
In locale vengono ricostruiti solo alcuni moduli

Tuttavia, build pulite, nuovi ambienti o runner aggiornati finiscono per rivelarlo. Fare la migrazione ora elimina instabilità nascoste.

Troubleshooting se le build falliscono ancora dopo la sostituzione

Controlla questi punti:

Ogni modulo è patchato. Guarda i moduli dei plugin, i moduli dell'app, i sample e gli asset del template.
Non c'è un secondo riferimento negli script condivisi. Cerca in tutti i repository (inclusi gli script Gradle personalizzati).
Le cache sono pulite. Esegui ./gradlew clean e fai il rebuild.
Le versioni di AGP / Gradle / JDK sono allineate.\nUsa combinazioni supportate dalla documentazione Android per la tua versione AGP.
La CI usa le stesse versioni dell'ambiente locale. Fissa le versioni di JDK e Gradle wrapper nella CI per evitare drift dell'ambiente.
Non stai patchando solo node_modules. Correggi il sorgente tracciato del plugin, non le directory delle dipendenze transitorie.

SEO FAQ: errori di build del plugin Capacitor con AGP 9

Come risolvere `proguard-android.txt` non trovato in AGP 9?

Sostituisci:

getDefaultProguardFile('proguard-android.txt')

Con:

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

Poi esegui un clean rebuild.

Perché il build del mio plugin Capacitor fallisce dopo l'aggiornamento ad Android Gradle Plugin 9?

Most failures come from legacy Gradle config in plugin android/build.gradle che fanno ancora riferimento a proguard-android.txt. I progetti AGP 9 dovrebbero usare proguard-android-optimize.txt.

Qual è il percorso di migrazione AGP 9 più veloce per molti plugin Capacitor?

Usa un comando search-and-replace su tutto il workspace, poi valida con git grep ed esegui bun run verify:android su plugin rappresentativi.

È solo un problema di Capacitor?

No. Qualsiasi modulo Android (app o libreria) che usi riferimenti ProGuard baseline deprecati può incappare in errori di build simili con AGP 9. È particolarmente evidente negli ecosistemi di plugin, perché molti repository condividono template vecchi.

Quali keyword sono rilevanti per questa migrazione?

Se lo documenti nei runbook interni o nelle pagine di supporto, includi termini come:

errore build AGP 9
Android Gradle Plugin 9: file ProGuard mancante
build Android del plugin Capacitor fallita
proguard-android.txt sostituzione
proguard-android-optimize.txt migrazione

Sviluppatori Android: Panoramica del build della tua app
Android Gradle Plugin: Note di rilascio
Shrinking code su Android: R8 e regole
Documentazione Gradle: Fondamentali degli strumenti di build
Documentazione Capacitor: Documentazione ufficiale
Capgo docs: Documentazione auto update

Considerazioni finali

Questo problema con AGP 9 è semplice, ma facile da ignorare in workspace con più plugin. Una volta sostituito proguard-android.txt con proguard-android-optimize.txt dove necessario, i build Android tornano a essere prevedibili.

Se usi i plugin Capgo, questa migrazione è già presente nei repository ufficiali per un upgrade senza sorprese.

Continua con Capacitor Plugin AGP 9 Build Error Fix

Se stai usando Correzione errore build AGP 9 del plugin Capacitor per pianificare l'automazione CI/CD e connetterla a CI/CD con Capgo per il workflow del prodotto in Capgo CI/CD, Capgo Native Build per il workflow di prodotto in Capgo Native Builds, Integrazioni Capgo per il workflow di prodotto in Integrazioni Capgo, Integrazione CI/CD per i dettagli implementativi in CI/CD Integration, e Integrazione GitHub Actions per i dettagli implementativi in GitHub Actions Integration.