Correzione dell'errore di costruzione del plugin AGP 9 Capacitor

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

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

Capacitor errore di costruzione del plugin AGP 9
Errore di costruzione del plugin AGP 9
proguard-android.txt non trovato
AGP 9 getDefaultProguardFile errore
Capacitor errore di costruzione Android dopo l'aggiornamento di AGP

La versione breve:

proguard-android.txt non è più il default di sicurezza di riferimento per le costruzioni del 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 spazi di lavoro Capacitor grandi. 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

In che contesto si riferisce a Android?

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

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

Quando cambiano le versioni di AGP, 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.

In che cosa si differenzia Capacitor?

targetLanguage":"Italian","protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"],"texts":["Capacitor","è un runtime cross-platform che ti consente di costruire app iOS/Android con web Capacitor (TypeScript, JavaScript, HTML, CSS) mentre ancora chiami API native.","Le app Capacitor includono di solito:","Un layer web (la tua UI e la tua logica di affari)","Guscio nativo (","I 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.","Se le impostazioni Gradle dei plugin sono obsolete, il tutto il build dell'applicazione può fallire, anche quando il tuo web Capacitor è corretto.","Cosa è Capacitor?","Capacitor","fornisce strumenti intorno alla consegna e alle operazioni di Capacitor:"] is a cross-platform runtime that lets you build iOS/Android apps with web code (TypeScript, JavaScript, HTML, CSS) while still calling native APIs.

Capacitor apps usually include:

translations.0.texts
translations.1.targetLanguageios/, android/)
translations.1.protectedTokens

translations.1.texts android/build.gradle translations.2.targetLanguage

If plugin Gradle settings are outdated, the whole app build can fail, even when your web code is correct.

What is Capgo?

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 amichevoli per Capacitor team

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

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

Questo è il motivo per cui sono importanti i ripari per la compatibilità con AGP 9: mantengono la layer di plugin affidabile affinché i pipeline di consegna rimangano predittibili.

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

Molti template di plugin hanno utilizzato nel passato:

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

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

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

Rapida panoramica: ProGuard, R8 e file di base

R8 is the modern code shrinker/optimizer in Android builds.
proguard-rules.pro è le regole di conservazione personalizzate del tuo progetto/plugin.
getDefaultProguardFile(...) inietta un baseline Android fornito.

Quando si fa riferimento:

proguard-android.txt -> baseline di base legacy
proguard-android-optimize.txt -> baseline ottimizzato moderno (impostazione predefinita consigliata nelle impostazioni correnti)

For 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 di plugin
Qualsiasi file generator/template che crea nuove configurazioni 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

Se il tuo plugin dispone di script di verifica completa, 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 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 è scomparso dai file dei plugin tracciati.

Capgo stato di rollout

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

I moduli dei plugin Android ora fanno riferimento a proguard-android-optimize.txt
Gli esempi di app Android dei plugin sono stati aggiornati pure
I modelli di scaffolding dei plugin sono stati aggiornati in modo che i nuovi plugin siano AGP 9-sicuri di default

Ciò impedisce una classe comune di errori di aggiornamento AGP 9 prima che raggiungano CI

Perché ciò è 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 sviluppo locale

Ma alla fine, le 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, i moduli dell'app, gli esempi e gli asset dei template.
Non ci sono riferimenti secondari nelle librerie condivise. Cerca interi repository (compresi script Gradle personalizzati).
Le cache sono pulite. 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 patchando node_modules. Correggi la fonte del plugin tracciato, non le directory delle dipendenze transitive.

Domande frequenti per la SEO: AGP 9 Capacitor plugin build errors

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 Capacitor plugin build fallisce dopo l'aggiornamento al plugin di compilazione Android Gradle 9?

La maggior parte delle fallite proviene da configurazioni di Gradle legacy nei file del plugin android/build.gradle che ancora si riferiscono a 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 pertinenti per questa migrazione?

Se documenti 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 replacement
proguard-android-optimize.txt migrazione

Sviluppatori di Android: Panoramica dell'applicazione
Plugin Gradle per Android: Note sulla versione
Android code riduzione dimensioni: R8 e regole
Documentazione Gradle: Fondamenti del tool di costruzione
Capacitor documentazione: Documentazione ufficiale
Capgo documentazione: Documentazione di aggiornamento automatico

Ricordo finale

Questo problema AGP 9 è semplice, ma è facile dimenticarlo nei lavori di spazi dei plugin multipli. Una volta sostituito proguard-android.txt con proguard-android-optimize.txt ovunque rilevante, le costruzioni 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 Capacitor Plugin AGP 9 Build Error Fix Se stai utilizzando il plugin di errore di costruzione AGP 9 di __CAPGO_KEEP_0__ per pianificare l'automazione CI/CD, connettilo con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD Capgo Costruzioni Native per il flusso di lavoro del prodotto in Capgo Costruzioni Native 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 di Azioni per il dettaglio di implementazione in GitHub Integrazione di Azioni

Capacitor Plugin AGP 9 Risoluzione dell'errore di build