Correzione dell'errore di costruzione del plugin AGP 9 Capacitor

Se il tuo Capacitor Il plugin non funziona più dopo l'aggiornamento al Plugin di costruzione di Android Gradle 9 (AGP 9), è probabile che stia colpendo un piccolo ma critico problema di configurazione di Gradle.

Questo post si concentra specificamente su intenzioni di ricerca comuni come:

Capacitor errore di costruzione del plugin AGP 9
Eseguire il plugin di costruzione di Android Gradle Plugin 9 non riuscito
proguard-android.txt non trovato
Plugin di costruzione di Android Gradle 9 getDefaultProguardFile errore
Capacitor costruzione di Android fallita dopo l'aggiornamento di AGP

La versione breve:

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

The version più lunga conta anche, soprattutto se gestisci 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é ciò conta per la affidabilità delle rilasci
L'esatto cambiamento 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 invii un'app o un plugin Capacitor su Android, il tuo progetto passa attraverso:

Gradle come il sistema di costruzione.
Plugin di Gradle per Android (AGP) come integrazione di Gradle specifica per Android.
Il toolkit Android SDK per la confezione, la riduzione, la verifica di sintassi e la produzione di .aar, .apk, o .aab gli output.

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

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.

Capacitor app includono di solito:

Una layer web (la tua interfaccia utente e la logica di business)
Gusci nativi (ios/, android/)
I plugin che espongono le 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, l'intero build dell'applicazione può fallire, anche quando il tuo pacchetto 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 bundle
Ecosistema dei plugin e pacchetti di funzionalità native
Flussi di aggiornamento amichevoli per i team di Capacitor

Anche con aggiornamenti in tempo reale, la stabilità dei costruzioni native non è negoziabile. È ancora necessario avere costruzioni Android pulite per:

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

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

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

Molti modelli di plugin utilizzavano in passato:

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

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

I sintomi tipici includono errori di Gradle durante assemble, lint, o build fasi, 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 unica

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"

Verifica quindi che nessun file di origine dei plugin tracciato utilizzi ancora il file vecchio:

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

No match significa che il riferimento di base vecchio è andato perso dai file dei plugin tracciati.

Stato di Capgo del rollout

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

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

Questo prevenire una classe comune di fallimenti di aggiornamento di 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'errore
Hai versioni miste di AGP nei progetti
Solo alcuni moduli vengono ricostruiti in dev locale

Ma alla fine, gli edifici puliti, gli ambienti nuovi o gli esecutori aggiornati lo espongono. Eseguire la migrazione ora elimina l'instabilità nascosta.

Risolvere i problemi se i costrutti 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 tutta la repository (compresi i script Gradle personalizzati).
Le cache sono pulite. Esegui ./gradlew clean e ricostruisci.
Le 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 di locale. 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

Come 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 non riesce a costruirsi dopo l'aggiornamento a Android Gradle Plugin 9?

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

Qual è la migrazione AGP 9 più veloce per molti plugin Capacitor?

Utilizza 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 costruzione AGP 9 simili. È specialmente visibile negli ecosistemi dei plugin perché molti repository condividono vecchi template.

Quali parole chiave sono rilevanti per questa migrazione?

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

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

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

Ricordo finale

Questo problema AGP 9 è semplice, ma è facile perdere di vista nei lavori di spazio plugin multipli. Una volta sostituito proguard-android.txt con proguard-android-optimize.txt ovunque rilevante, gli Android diventano prevedibili di nuovo.

Se utilizzate i plugin Capgo, questa migrazione è già stata applicata nei repository ufficiali quindi potete aggiornare con meno sorprese.

Capacitor Plugin AGP 9 Risoluzione dell'errore di costruzione