Se la tua Capacitor il plugin ha iniziato a fallire dopo l'aggiornamento ad Android Gradle Plugin 9 (AGP 9), probabilmente stai riscontrando un piccolo ma critico problema di configurazione Gradle.
Questo post si concentra specificamente su intent di ricerca comuni come:
- errore di build del plugin Capacitor AGP 9
- Android Gradle Plugin 9 build del plugin non riuscita
proguard-android.txtnon trovato- AGP 9
getDefaultProguardFileerrore - build Android di Capacitor non riuscita dopo l'aggiornamento ad AGP
The short version:
proguard-android.txtnon è più la baseline di riferimento sicura per i build dei plugin in AGP 9.- Passa a
proguard-android-optimize.txt. - Ricostruisci e verifica.
Anche la versione lunga conta, soprattutto se mantieni molti plugin o grandi workspace Capacitor. In questo articolo copriamo:
- Cosa sono Android e AGP nella build chain
- Cosa è Capacitor e come funzionano i build dei plugin
- Cosa è Capgo e perché è importante per l'affidabilità dei release
- La modifica esatta in AGP 9 che rompe i vecchi template dei plugin
- Una strategia di migrazione sicura per un repo o per molti repo
Che 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 attraversa:
- 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 build nativa. 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'intera build dell'app può fallire, anche se il tuo web code è corretto.
Cos'è Capgo?
Capgo fornisce strumenti per la distribuzione 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 i team Capacitor
Anche con gli aggiornamenti live, la stabilità dei build nativi è imprescindibile. Servono comunque 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
Per questo le correzioni di compatibilità con AGP 9 sono importanti: mantengono il layer dei plugin affidabile, così le pipeline di delivery restano prevedibili.
Perché AGP 9 rompe le vecchie configurazioni dei plugin
Molti template di plugin usavano storicamente:
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
Nei setup con AGP 9, questo riferimento legacy al baseline può fallire perché il vecchio file non è più garantito nella posizione prevista dai template/config più vecchi.
I sintomi tipici includono errori Gradle durante assemble, lint, o build le fasi, spesso dovuti a risorse baseline ProGuard mancanti o riferimenti a file predefiniti non validi.
Breve ripasso: ProGuard, R8 e file baseline
- R8 è il moderno shrinker/ottimizzatore code nelle build Android.
proguard-rules.prosono le regole keep personalizzate del tuo progetto/plugin.getDefaultProguardFile(...)inietta una baseline fornita da Android.
Quando fai riferimento a:
proguard-android.txt-> baseline legacy, minimaproguard-android-optimize.txt-> baseline moderna ottimizzata (predefinito consigliato nelle configurazioni attuali)
Per la compatibilità con AGP 9, passa a proguard-android-optimize.txt è la soluzione pratica.
La soluzione in una riga
Aggiorna i file Gradle del plugin e del modulo app:
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
Al minimo, verifica:
android/build.gradlein ogni pluginexample-app/android/app/build.gradlenei repository dei plugin- Qualsiasi file generatore/template che crea una nuova configurazione Gradle per il plugin
Guida alla migrazione per un singolo 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
Aggiorna in batch tutti i repo dei plugin
Se mantieni 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 nessuna sorgente di plugin tracciata 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 correggo proguard-android.txt non trovato in AGP 9?
Sostituisci:
getDefaultProguardFile('proguard-android.txt')
Con:
getDefaultProguardFile('proguard-android-optimize.txt')
Poi esegui una rebuild pulita.
Perché il build del plugin Capacitor fallisce dopo l'aggiornamento ad Android Gradle Plugin 9?
La maggior parte dei fallimenti deriva da configurazioni Gradle legacy nel plugin android/build.gradle file 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 di ricerca e sostituzione su tutto il workspace, poi valida con git grep e 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 sulla build dell'app
- Android Gradle Plugin: Note di rilascio
- Riduzione di code per Android: R8 e regole
- Documentazione Gradle: Fondamenti degli strumenti di build
- Documentazione di Capacitor: Documentazione ufficiale
- docs di Capgo: Docs aggiornamento automatico
In sintesi
Questo problema di AGP 9 è semplice, ma è facile da trascurare nei workspace multi-plugin. Una volta sostituito proguard-android.txt con proguard-android-optimize.txt ovunque necessario, le build Android tornano prevedibili.
Se usi i plugin di Capgo, questa migrazione è già applicata nei repository ufficiali, così puoi aggiornare con meno 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.