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 risponde specificamente a ricerche come:
- errore build plugin Capacitor AGP 9
- Errore durante la build del plugin con Android Gradle Plugin 9
proguard-android.txtnon trovato- AGP 9
getDefaultProguardFileerrore - Build Android Capacitor fallita dopo upgrade AGP
The short version:
proguard-android.txtnon è più il baseline di default sicuro da utilizzare nei build dei plugin con AGP 9.- Passa a
proguard-android-optimize.txt. - Ricompila e verifica.
Anche la versione estesa è 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 i 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.aaboutput.
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 la gestione e il delivery di Capacitor:
- Live Update per modifiche al bundle web
- Ecosistema di plugin e pacchetti per feature native
- Workflow di aggiornamento CI/CD-friendly per team Capacitor
Anche con i Live Update, la stabilità del Native Build è fondamentale. Ti servono build Android pulite per:
- Rilasci su App Store / Play Store
- Upgrade dei plugin nativi
- Migrazioni SDK della piattaforma
- 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 di plugin usavano:
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
Nelle configurazioni AGP 9, questo riferimento legacy può fallire perché il vecchio file non è più garantito nella posizione prevista dai vecchi template/config.
I sintomi tipici includono errori Gradle durante le assemble, lint, o build fasi, spesso indicando la mancanza di risorse ProGuard baseline o riferimenti a file predefiniti non validi.
Breve riepilogo: ProGuard, R8 e file baseline
- R8 è il moderno code shrinker/optimizer per le build Android.
proguard-rules.prosono le regole personalizzate del tuo progetto/plugin.getDefaultProguardFile(...)inietta una baseline fornita da Android.
Quando si fa riferimento a:
proguard-android.txt-> baseline legacy, minimaproguard-android-optimize.txt-> baseline moderna e ottimizzata (default consigliato nelle configurazioni attuali)
Per la compatibilità con AGP 9, passare a proguard-android-optimize.txt è la soluzione pratica.
La correzione 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.gradlein ogni pluginexample-app/android/app/build.gradlenei repo dei plugin- Eventuali file generator/template che creano la nuova config Gradle del plugin
Guida alla migrazione per 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 il processo:
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 verifica che nessun codice sorgente dei plugin tracciati utilizzi 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 cleane 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 plugin Capacitor fallisce dopo l'aggiornamento ad Android Gradle Plugin 9?
La maggior parte degli errori deriva da vecchie configurazioni Gradle nei file android/build.gradle dei plugin che fanno ancora riferimento a proguard-android.txt. I progetti AGP 9 dovrebbero usare proguard-android-optimize.txt.
Qual è la via più veloce per migrare molti plugin Capacitor ad AGP 9?
Usa un comando search-and-replace su tutto il workspace, quindi 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.txtsostituzioneproguard-android-optimize.txtmigrazione
Link correlati
- Sviluppatori Android: Panoramica sul build della tua app
- Android Gradle Plugin: Note di rilascio
- Shrinking code su Android: R8 e regole
- Documentazione Gradle: Fondamentali dei build tool
- Documentazione Capacitor: Documentazione ufficiale
- Capgo docs: Documentazione aggiornamento automatico
In sintesi
Il 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 ogni riferimento pertinente, le build Android tornano a essere prevedibili.
Se utilizzi i plugin Capgo, questa migrazione è già presente nei repository ufficiali per un upgrade senza sorprese.
Continua con: correzione dell'errore di build AGP 9 per i plugin Capacitor
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.