Correzione dell'errore di costruzione del plugin AGP 9 Capacitor

Se il tuo Capacitor Il plugin ha iniziato a fallire dopo l'aggiornamento al Plugin di Gradle per Android 9 (AGP 9), è probabile che stia colpendo un piccolo ma critico problema di configurazione di Gradle.

Questo post si concentra specificamente sugli intenti di ricerca comuni come:

Capacitor errore di compilazione del plugin AGP 9
Plugin di compilazione del plugin AGP 9 fallito
proguard-android.txt non trovato
AGP 9 getDefaultProguardFile errore
Capacitor fallimento della compilazione Android dopo l'aggiornamento di AGP

La versione breve:

proguard-android.txt non è più il default di sicurezza di riferimento per le compilazioni del plugin AGP 9.
Passa a proguard-android-optimize.txt.
Ricompila e verifica.

La versione più lunga conta anche, soprattutto se si gestiscono molti plugin o grandi Capacitor ambienti di lavoro. In questo articolo copriamo:

Cosa sono Android e AGP nella catena di costruzione
Cosa è Capacitor e come funzionano le costruzioni dei plugin
Cosa Capgo è e perché conta per la affidabilità delle release
Il cambiamento esatto di AGP 9 che rompe gli antichi template dei plugin
Una strategia di migrazione sicura per un repository o molti repository

Cosa è Android in questo contesto?

Android è sia un sistema operativo che un ecosistema di costruzione. Quando si invia un'app o un plugin Capacitor su Android, il progetto passa attraverso:

Gradle As il sistema di costruzione.
Plugin Android Gradle (AGP) As integrazione Android-specifica di Gradle.
La piattaforma di sviluppo Android SDK per la confezione, la riduzione, la verifica di sintassi e la produzione .aar, .apk, o .aab I risultati.

Quando le versioni di AGP cambiano, alcuni valori predefiniti e file interni possono cambiare anche loro. Una configurazione di plugin che funzionava per AGP 8 può fallire su AGP 9 se punta a una baseline rimossa o deprecata.

Cosa è Capacitor?

Capacitor è un runtime cross-platform che ti consente di costruire app iOS/Android con web code (TypeScript, JavaScript, HTML, CSS) mentre puoi ancora chiamare API native.

Gli app Capacitor includono generalmente:

Una layer web (la tua interfaccia utente e la logica di business)
Gusci nativi (ios/, android/)
I plugin che espongono funzionalità native al JavaScript

Ogni plugin ha la propria configurazione di build nativa. Su Android, ciò significa che ogni plugin include un android/build.gradle file che AGP deve interpretare e compilare correttamente.

Se le impostazioni Gradle dei plugin sono obsolete, il tutto il build dell'applicazione può fallire, anche quando il tuo web code è corretto.

Cosa è Capgo?

Capgo fornisce strumenti per la consegna e le operazioni di Capacitor:

Aggiornamenti in tempo reale per modifiche al pacchetto web
Ecosistema dei plugin e pacchetti di funzionalità native
Flussi di lavoro di aggiornamento compatibili con CI/CD per le squadre di Capacitor

Anche con aggiornamenti in tempo reale, la stabilità dei costruzioni native non è negoziabile. In ogni caso, avete ancora bisogno di costruzioni Android pulite per:

Rilasci di App Store / Play Store
Aggiornamenti di plugin nativi
Migrazioni della piattaforma SDK
Assunzione di nuovi membri del team e affidabilità di CI

Questo è il motivo per cui sono importanti i ripari per la compatibilità con AGP 9: mantengono la vostra layer di plugin affidabile, quindi i flussi di consegna rimangono predittibili.

Perché AGP 9 rompe le configurazioni dei plugin più vecchie

Molti modelli di plugin hanno utilizzato storici:

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

In impostazioni AGP 9, questa riferimento di base di vecchia epoca può fallire perché il vecchio file non è più garantito nella posizione attesa dai modelli/config di vecchia epoca.

I sintomi tipici includono errori di Gradle durante assemble, lint, o build fasce, spesso che puntano a risorse di ProGuard mancanti o riferimenti di file di default invalidi.

Rapida panoramica: ProGuard, R8 e file di base

R8 is the modern code shrinker/optimizer in Android builds.
proguard-rules.pro hai impostato regole di conservazione personalizzate per il tuo progetto/plugin.
getDefaultProguardFile(...) inietta un file di base fornito da Android.

Quando si fa riferimento a:

proguard-android.txt -> file di base legacy, minimo
proguard-android-optimize.txt -> file di base ottimizzato moderno (impostazione predefinita consigliata negli attuali setup)

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

La soluzione di una riga

Aggiorna i file Gradle del plugin e del modulo dell'applicazione:

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

At minimum, controlla:

android/build.gradle in ogni plugin
example-app/android/app/build.gradle in repository dei plugin
Qualsiasi file generatore/template che crea una nuova configurazione Gradle per plugin

Guida di migrazione per un plugin

1. Trova la vecchia referenza

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

2. Sostituiscila

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 dispone di script di verifica completi, esegui:

bun run verify

Aggiorna in batch tutti i repository dei plugin

Se mantieni molti repository dei plugin in un unico ambiente di lavoro, automatizzalo:

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"

Infine, verifica che nessuna fonte di plugin tracciata utilizza 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 riferimento di base vecchio è andato perso dai file dei plugin tracciati.

Stato di Capgo

Eseguiamo questa migrazione su tutti i repository e i modelli ufficiali di Capgo Capacitor plugin:

I moduli dei plugin Android ora fanno riferimento a proguard-android-optimize.txt
Il plugin esempio delle app Android sono stati aggiornati anche
I modelli di scaffolding dei plugin sono stati aggiornati in modo che i nuovi plugin siano sicuri per impostazione predefinita AGP 9.

Questo prevenire una classe comune di fallimenti di aggiornamento AGP 9 prima che colpiscano CI.

Perché è importante anche se il tuo build passa oggi

Potresti non vedere fallimenti immediatamente se:

La cache di CI ancora maschera l'issue
Hai versioni miste di AGP nei progetti
Solo alcuni moduli vengono ricostruiti in dev locale

But eventualmente, le costruzioni pulite, gli ambienti nuovi o gli esecutori aggiornati lo espongono. Eseguire la migrazione ora elimina l'instabilità nascosta.

Risolvere i problemi se i costruzioni falliscono ancora dopo la sostituzione

Controlla questi punti:

Ogni modulo è stato patchato. Guarda i moduli dei plugin, i moduli dell'applicazione, gli esempi e gli asset dei template.
Non ci sono riferimenti secondari nei script condivisi. Cerca interi repository (compresi script Gradle personalizzati).
I cache sono puliti. Esegui ./gradlew clean e ricostruisci.
I versioni di AGP / Gradle / JDK sono allineate. Utilizza combinazioni supportate dalla documentazione Android per la tua versione di AGP.
Il CI utilizza le stesse versioni locali. Fissa le versioni del wrapper Gradle e del JDK in CI per evitare la deriva dell'ambiente.
Non stai patchando solo node_modules. Risolve le fonti dei plugin tracciate, non le directory delle dipendenze transitive.

FAQ SEO: AGP 9 Capacitor errori di costruzione dei plugin

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

Sostituisci:

getDefaultProguardFile('proguard-android.txt')

Con:

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

E quindi esegui una ricostruzione pulita.

Perché il mio plugin Capacitor si rifiuta di costruirsi dopo l'aggiornamento al Plugin di Gradle per Android 9?

La maggior parte delle fallite proviene da configurazioni di Gradle legacy nei plugin android/build.gradle i file che ancora si riferiscono a proguard-android.txt. I progetti AGP 9 dovrebbero utilizzare proguard-android-optimize.txt.

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

Usa un comando di ricerca e sostituzione su tutto il workspace, poi valuta con git grep e esegui bun run verify:android i plugin rappresentativi.

È questo solo un problema di Capacitor?

No. Qualsiasi modulo Android (app o libreria) che utilizza riferimenti di baseline ProGuard obsoleti può incontrare errori di build AGP 9 simili. È specialmente visibile negli ecosistemi dei plugin perché molti repository condividono vecchi template.

Quali parole chiave sono pertinenti per questa migrazione?

Se documentate questo in runbook interni o pagine di supporto, includete termini come:

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

Sviluppatori di Android: Panoramica dell'applicazione
Plugin Gradle per Android: Nota delle versioni
Riduzione del file Android code: R8 e regole
Documentazione Gradle: Fondamenti del tool di costruzione
Documentazione Capacitor: Documentazione ufficiale
Documentazione Capgo: Documentazione dell'aggiornamento automatico

Ricordo finale

Questa questione AGP 9 è semplice, ma è facile perdere di vista nei lavori di workspace multi-plugin. Una volta sostituito proguard-android.txt con proguard-android-optimize.txt tutto ciò che è rilevante, gli edifici Android diventano di nuovo predittibili.

If you use Capgo plugins, this migration is already applied in official repositories so you can upgrade with fewer surprises.

Capacitor

questa migrazione è già stata applicata nei repository ufficiali quindi si può aggiornare con meno sorprese. Capacitor Plugin AGP 9 Build Error Fix __CAPGO_KEEP_0__ Capgo CI/CD for the product workflow in Capgo CI/CD, Capgo for the product workflow in Capgo Native Builds, Capgo Integrazioni per il flusso di lavoro del prodotto in Capgo Integrazioni, Integrazione CI/CD per il dettaglio di implementazione in Integrazione CI/CD, e GitHub Integrazione delle azioni per il dettaglio di implementazione in GitHub Integrazione delle azioni.

Capacitor Plugin AGP 9 Build Error Fix