Correzione dell'errore di build del plugin AGP 9 Capacitor

Se il tuo Capacitor Se il tuo plugin inizia a fallire dopo l'aggiornamento a Android Gradle Plugin 9 (AGP 9), è probabile che stia incontrando un piccolo ma critico problema di configurazione di Gradle.

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

Capacitor plugin build error AGP 9
plugin di costruzione di Android Gradle Plugin 9 fallito
proguard-android.txt non trovato
AGP 9 getDefaultProguardFile errore
Capacitor build Android fallito dopo l'aggiornamento di AGP

La versione breve:

proguard-android.txt non è più il default di riferimento sicuro per le build dei plugin AGP 9.
Passa a proguard-android-optimize.txt.
Riavvia e verifica.

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

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

Cosa significa Android in questo contesto?

Android is both an operating system and a build ecosystem. When you ship a Capacitor app or plugin on Android, your project goes through:

Gradle come sistema di costruzione.
Android Gradle Plugin (AGP) come integrazione di Gradle specifica per Android.
The Android SDK toolchain for packaging, shrinking, linting, and producing .aar, .apk, o .aab output.

Quando cambiano le versioni di AGP, alcuni valori predefiniti e file interni possono cambiare anch'essi. 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 creare app iOS/Android con web code (TypeScript, JavaScript, HTML, CSS) mentre ancora chiami API native.

Capacitor

Una layer web (la tua interfaccia utente e la logica d'azienda)
Native shells (ios/, android/)
Plugin che espongono funzionalità native al JavaScript

Ogni plugin ha la sua configurazione di build nativa. Su Android, ciò significa che ogni plugin include un file che AGP deve analizzare e compilare correttamente. android/build.gradle Se le impostazioni Gradle dei plugin sono obsolete, il tutto il build dell'app può fallire, anche quando il tuo web __CAPGO_KEEP_0__ è corretto.

Di cosa si tratta code?

Capgo

fornisce strumenti intorno alla Capgo di consegna e operazioni: provides tools around Capacitor delivery and operations:

Aggiornamenti in tempo reale per modifiche al bundle web
Ecosistema di plugin e pacchetti di funzionalità native
Flussi di aggiornamento CI/CD adatti per Capacitor team

Anche con gli aggiornamenti in tempo reale, la stabilità dei build nativi non è negoziabile. Hai ancora bisogno di build Android puliti per:

Rilasci su App Store / Play Store
Aggiornamenti di plugin nativi
Migrazioni alla piattaforma SDK
Assunzione di team e affidabilità di CI

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

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

Molti template di plugin hanno utilizzato in passato:

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

In impostazioni AGP 9, questa riferimento di base legacy può fallire perché il vecchio file non è più garantito nella posizione attesa dalle vecchie template/config.

Tipici sintomi includono errori Gradle durante assemble, lint, o build le fasi, spesso che puntano a risorse di baseline ProGuard mancanti o riferimenti di file predefiniti invalidi.

Rapida panoramica: ProGuard, R8 e file di baseline

R8 è il moderno code riduttore/ottimizzatore in costruzioni Android.
proguard-rules.pro è le regole di conservazione personalizzate del tuo progetto/plugin.
getDefaultProguardFile(...) inietta un baseline Android fornito.

Quando si fa riferimento a:

proguard-android.txt -> baseline di base legacy, minima
proguard-android-optimize.txt -> baseline di base moderna ottimizzata (impostazione predefinita consigliata nelle impostazioni correnti)

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

La soluzione di una riga

Aggiornare i file Gradle dei plugin e dei moduli dell'applicazione:

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

Almeno, controlla:

android/build.gradle in ogni plugin
example-app/android/app/build.gradle in repository dei plugin
Qualsiasi file generator/template che crea nuove configurazioni Gradle dei 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

If il tuo plugin dispone di script di verifica completa, esegui:

bun run verify

Eseguisci un aggiornamento batch di tutti i repository dei plugin

Se gestisci 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 nessuna fonte dei plugin tracciati utilizza ancora il file vecchio:

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

Nessuna corrispondenza significa che la riferimento di baseline vecchio è andato perduto dai file dei plugin tracciati.

Capgo stato dello rollout

Abbiamo completato questa migrazione in tutti i repository dei plugin ufficiali Capgo Capacitor e nei modelli:

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

Ciò preveniva una classe comune di errori di aggiornamento AGP 9 prima che raggiungessero CI.

Perché è importante anche se il tuo build passa oggi

Potresti non vedere gli errori immediatamente se:

Il tuo cache CI ancora maschera il problema
Hai versioni AGP diverse tra i progetti
Solo alcune librerie vengono ricostruite in ambiente di sviluppo locale

Ma alla fine, i costruzioni pulite, nuovi ambienti o runner aggiornati espongono il problema. Eseguire la migrazione ora elimina instabilità nascoste.

Risolvere i problemi se le costruzioni falliscono ancora dopo la sostituzione

Controlla questi punti:

Tutte le librerie sono state patchate. Guarda le librerie dei plugin, le librerie dell'app, gli esempi e gli asset dei template.
Non ci sono riferimenti secondari in script condivisi. Cerca tutta la repository (compresi script Gradle personalizzati).
I cache sono puliti. Esegui ./gradlew clean e ricostruisci.
Le versioni AGP / Gradle / JDK sono allineate. Usa combinazioni supportate dalla documentazione Android per la tua versione AGP.
Il CI utilizza le stesse versioni di quelle locali. Blocca le versioni di JDK e wrapper Gradle in CI per evitare la deriva dell'ambiente.
Non stai solo patching node_modules. Risolvi la fonte del plugin tracciato, non le directory delle dipendenze transitive.

Domande frequenti di SEO: AGP 9 Capacitor errori di compilazione del plugin

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

Sostituisci:

getDefaultProguardFile('proguard-android.txt')

Con:

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

Eseguisci quindi una ricostruzione pulita.

Perché il mio Capacitor plugin di compilazione fallisce dopo l'aggiornamento al Plugin di Gradle Android 9?

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

Qual è la 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 su 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 rilevanti per questa migrazione?

Se stai documentando questo nei runbook interni o nelle pagine di supporto, includi termini come:

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

Android Developers: Panoramica della creazione dell'app
Android Gradle Plugin: Nota delle versioni
Android code shrinking: R8 e regole
Documentazione Gradle: Fondamenti del tool di costruzione
Documentazione Capacitor: Documentazione ufficiale
Capgo documentazione: Documentazione di aggiornamento automatico

Ultimo punto da tenere a mente

Questo problema di AGP 9 è semplice, ma è facile perdere di vista in ambienti di lavoro multi-plugin. Una volta sostituito proguard-android.txt con proguard-android-optimize.txt ovunque rilevante, gli build 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 plugin, questa migrazione è già stata applicata nei repository ufficiali, quindi puoi aggiornare con meno sorprese.

Continua da qui: Capacitor Plugin AGP 9 Build Error Fix __CAPGO_KEEP_0__ Plugin AGP 9 Build Error Fix per pianificare l'automazione CI/CD, connettilo con Capgo CI/CD per il workflow del prodotto in Capgo CI/CD Capgo Costruzioni native per il workflow del prodotto in Capgo Costruzioni native Capgo Integrazioni for the product workflow in Capgo Integrations, per il workflow del prodotto in __CAPGO_KEEP_0__ Integrazioni Integrazione CI/CD GitHub Actions Integration for the implementation detail in GitHub Actions Integration.

Capacitor Plugin AGP 9 Build Error Fix