Risolvi l'errore di build del plugin AGP 9 Capacitor

Se il tuo Capacitor se il tuo plugin di Capacitor inizia a fallire dopo l'aggiornamento al Plugin di Costruzione Android 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 AGP 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 trattiamo:

Cosa sono Android e AGP nella catena di build
Cosa è Capacitor e come funzionano le build dei plugin
Cosa Capgo contexto: frammento di testo HTML da una stringa di Capgo UI più lunga (chiave padre `submitting_a_pr_to_capgo`). Area: Sito web di marketing di Capgo. Ruolo: Testo del sito web. Visualizzato in: pagina contribuisci.astro. Preservare esattamente i termini del prodotto e della marca di Capgo e i termini dei developer.
è e perché ciò conta per la affidabilità delle release
L'effettiva modifica AGP 9 che rompe gli antichi template dei plugin

What is Android in this context?

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.
Plugin Android Gradle (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 puntava a una baseline rimossa o obsoleta.

What is Capacitor?

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

Capacitor

Una layer web (la tua UI e la tua logica di business)
Scheletri nativi (ios/, android/)
Plugin che espongono funzionalità native al JavaScript

Ogni plugin ha la sua propria 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 build dell'app intera può fallire, anche quando il tuo web __CAPGO_KEEP_0__ è corretto.

Di cosa si tratta code?

Capgo

fornisce strumenti per la consegna e le operazioni di Capgo: 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 per Capacitor squadre

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

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

Questo è il motivo per cui sono importanti i fix di compatibilità con AGP 9: mantengono la layer di plugin affidabile, quindi i pipeline 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.

Il sintomo tipico include gli errori di Gradle durante assemble, lint, o build le fasi, spesso che puntano a risorse di baseline ProGuard mancanti o riferimenti di file predefiniti invalidi.

Riepilogo rapido: 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 -> riferimento di base legacy, minimo
proguard-android-optimize.txt -> riferimento di base ottimizzato moderno (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

Aggiorna 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 una nuova configurazione Gradle del 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

Aggiorna in blocco 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"

Poi verifica 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

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

Capgo status dello stato di rilascio

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

I moduli Android dei plugin ora fanno riferimento a proguard-android-optimize.txt
Il plugin esempi di app Android sono stati aggiornati anche loro
I template di scaffolding dei plugin sono stati aggiornati in modo che i nuovi plugin siano sicuri per impostazione predefinita per l'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:

La cache del tuo CI ancora maschera l'errore
Hai versioni miste di AGP nei progetti
Solo alcuni moduli vengono ricostruiti in sviluppo locale

Ma alla fine, i costruttori puliti, nuovi ambienti o runner aggiornati espongono il problema. Eseguire la migrazione ora elimina l'instabilità nascosta.

Risolvere i problemi se i costruttori ancora falliscono dopo la sostituzione

Controlla questi punti:

Ogni modulo è stato patchato. Guarda i moduli dei plugin, i moduli dell'app, gli esempi e gli asset dei template.
C'è una seconda referenza in script condivisi. Cerca tutta la repository (compresi i script Gradle personalizzati).
I cache sono puliti. Esegui e ricostruisci. ./gradlew clean I versioni di AGP / Gradle / JDK sono allineate. Usa combinazioni supportate dalla documentazione Android per la tua versione di AGP.
Risultati di ricerca
Il CI utilizza le stesse versioni di quelle locali. Blocca le versioni di JDK e wrapper Gradle nel CI per evitare la deriva dell'ambiente.
Non stai solo patchando node_modules. Risolvi la fonte del plugin tracciato, non i directory delle dipendenze transitive.

Domande frequenti per la SEO: AGP 9 Capacitor errori di build 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 build 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 di workspace, quindi 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 pertinenti 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 riconoscimento
proguard-android-optimize.txt migrazione

Android Developers: Panoramica della creazione dell'app
Android Gradle Plugin: Note di rilascio
Android code riduzione dimensioni: R8 e regole
Documentazione Gradle: Principi fondamentali del tool di costruzione
Capacitor documentazione: Documentazione ufficiale
Capgo documentazione: Documentazione di aggiornamento automatico

Ricordo finale

Questo problema di AGP 9 è semplice, ma è facile perdere di vista nei progetti 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 si può 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