Salta al contenuto principale

Correzione errore build AGP 9 del plugin Capacitor

Risolvi rapidamente gli errori di build dei plugin Capacitor con AGP 9. Scopri perché proguard-android.txt fallisce, come usare proguard-android-optimize.txt e come Capgo ha risolto i problemi di Android Gradle Plugin 9 tra i vari plugin.

Correzione errore di build del plugin Capacitor con AGP 9 Capgo illustrazione blog

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.txt non trovato
  • AGP 9 getDefaultProguardFile errore
  • build Android di Capacitor non riuscita dopo l'aggiornamento ad AGP

The short version:

  • proguard-android.txt non è 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:

  1. Gradle come sistema di build.
  2. Android Gradle Plugin (AGP) come integrazione Gradle specifica per Android.
  3. 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 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.pro sono le regole keep personalizzate del tuo progetto/plugin.
  • getDefaultProguardFile(...) inietta una baseline fornita da Android.

Quando fai riferimento a:

  • proguard-android.txt -> baseline legacy, minima
  • proguard-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.gradle in ogni plugin
  • example-app/android/app/build.gradle nei 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:

  1. Ogni modulo è patchato. Guarda i moduli dei plugin, i moduli dell'app, i sample e gli asset del template.

  2. Non c'è un secondo riferimento negli script condivisi. Cerca in tutti i repository (inclusi gli script Gradle personalizzati).

  3. Le cache sono pulite. Esegui ./gradlew clean e fai il rebuild.

  4. Le versioni di AGP / Gradle / JDK sono allineate.\nUsa combinazioni supportate dalla documentazione Android per la tua versione AGP.

  5. La CI usa le stesse versioni dell'ambiente locale. Fissa le versioni di JDK e Gradle wrapper nella CI per evitare drift dell'ambiente.

  6. 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.txt sostituzione
  • proguard-android-optimize.txt migrazione

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.

Live updates per le app Capacitor

Quando un bug nel web-layer è live, rilascia la fix tramite Capgo invece di aspettare giorni l'approvazione degli store. Gli utenti ricevono l'update in background, mentre le modifiche native restano nel normale processo di review.

Ultimi articoli dal blog

Capgo ti offre gli insight migliori che ti servono per creare un'app mobile davvero professionale.