Android Gradle Plugin (AGP) è il sistema di compilazione supportato per le applicazioni Android e include il supporto per la compilazione di molti tipi diversi di origini e il loro collegamento in un'applicazione che puoi eseguire su un dispositivo Android fisico o un emulatore.
La sezione seguente descrive l'evoluzione pianificata del linguaggio specifico del dominio e dell'API di AGP. Man mano che vengono introdotte nuove API nelle release stabili, quelle precedenti verranno contrassegnate come obsolete. Queste API deprecate non saranno più disponibili nella successiva release stabile. Le sezioni seguenti forniscono informazioni sulle prossime modifiche in ogni release principale di AGP.
Per un log più dettagliato dei ritiri o delle rimozioni delle API AGP, consulta gli aggiornamenti delle API AGP.
AGP 10.0 (fine 2026)
Modifiche e modernizzazione dell'API del plug-in Android per Gradle 10.0
AGP 10.0 completa la transizione a un modello di build completamente lazy e compatibile con la cache di configurazione. Questa release è il culmine di un impegno pluriennale per sostituire le API legacy non lazy con un'architettura più sicura e performante.
Perché un modello di build lazy?
Nel modello di build legacy non lazy, Gradle valuta gli oggetti, esegue query sui dati delle varianti e configura le attività in tutti i moduli del progetto durante ogni sincronizzazione o invocazione della build. Questa valutazione eager spreca tempo della CPU e memoria per varianti e attività che non sono in esecuzione e causa conflitti di ordinamento della valutazione in script di build complessi.
Passando a un modello di build completamente lazy utilizzando i provider lazy
(Provider<T>) e la moderna API Variant (androidComponents {}), le proprietà
e il collegamento delle attività vengono calcolati in modo lazy su richiesta solo quando necessario per il
grafico di esecuzione della build attivo.
Le API legacy rimosse in questa release erano fondamentalmente incompatibili con questa architettura moderna. La loro rimozione consente ad AGP di supportare completamente la cache di configurazione di Gradle e l'isolamento del progetto, il che migliora drasticamente le velocità di build e i tempi di sincronizzazione in Android Studio.
La differenza architettonica principale
La precedente API BaseVariant (applicationVariants.all {}) era eager e
incentrata sulle attività. Durante la fase di configurazione, gli sviluppatori avevano accesso diretto alle attività Gradle e alle configurazioni interne, il che interrompe intrinsecamente le moderne funzionalità di rendimento di Gradle.
La nuova API Variant (androidComponents {}) è pigra e incentrata sugli artefatti. Utilizza
ampiamente l'API Property di Gradle e rimuove completamente tutti i riferimenti a
Task e TaskProvider, richiedendo di interagire in modo pulito con gli input e
gli output (Variant.artifacts) anziché con le attività sottostanti.
Che cosa viene rimosso e sostituito
Tutte le interfacce e le classi precedenti utilizzate nel DSL legacy e nella vecchia API Variant vengono eliminate. Per preparare gli script di build e i plug-in personalizzati, esegui la migrazione dalle seguenti API e dai seguenti flag di fine ciclo di vita:
| API o funzionalità rimossa | Sostituzione o azione necessaria |
|---|---|
Accesso diretto all'attività:
|
API Artifacts: anziché recuperare l'attività per
modificarne il comportamento, utilizza variant.artifacts per
aggiungere, modificare o sostituire i file effettivi (artefatti) che passano da un'attività
all'altra.
|
Registrazione eager dell'origine:
|
API Sources:collega la directory di output dell'attività personalizzata utilizzando variant.sources.java.addGeneratedSourceDirectory(...).
|
Accesso a classpath / configurazione:
|
L'API Instrumentation:per modificare o ispezionare il bytecode
(il caso d'uso più comune per l'accesso al classpath), utilizza
variant.instrumentation.transformClassesWith(...) utilizzando
AsmClassVisitorFactory.
|
Mutazione della proprietà eager:
|
Istanze di `MapProperty` lazy:utilizza
variant.buildConfigFields.put(...) e
variant.manifestPlaceholders.put(...).
|
Flag di disattivazione:
|
Nessuna sostituzione diretta. Rimuovi questi flag da
gradle.properties; il DSL moderno e Kotlin integrato sono
applicati rigorosamente.
|
Estensioni dell'API Variant legacy:
|
Sostituisci con androidComponents.onVariants(). |
Filtro delle varianti (blocco variantFilter) |
Sostituisci con androidComponents.beforeVariants() utilizzando
i selettori di varianti.
|
Componenti SDK e NDK:
|
Accedi ai componenti dell'SDK utilizzando
androidComponents.sdkComponents.
|
Ambienti di test:
|
Esegui la migrazione della registrazione dei dispositivi di test personalizzati ai dispositivi gestiti da Gradle. |
API di registrazione obsolete:
|
Eliminato senza sostituzione diretta. |
| API Transform |
Sostituisci le trasformazioni con l'API Artifacts e
AsmClassVisitorFactory.
|
Per accedere a tutte le interfacce e le classi DSL e API Variant di sostituzione (androidComponents {}),
utilizza sempre l'artefatto gradle-api quando sviluppi plug-in Gradle personalizzati o logica di build.
Passi per la migrazione
Per rendere l'upgrade ad AGP 10.0 semplice e prevedibile, segui queste pratiche di migrazione:
- Esegui l'assistente per l'upgrade di AGP:prima di eseguire l'upgrade diretto alla versione 10.0, esegui
l'assistente per l'upgrade di AGP ufficiale in
Android Studio (
Tools > AGP Upgrade Assistant). Automatizza diverse migrazioni comuni di DSL e script di build e contribuisce a preservare i comportamenti di build esistenti. - Utilizza le competenze di Agent Mode in Android Studio:sfrutta le competenze di upgrade dell'AI (come le competenze di upgrade di AGP disponibili nel repository delle competenze Android) per automatizzare e semplificare la migrazione di logica di build e DSL complesse in Android Studio.
- Correggi prima gli avvisi di ritiro in AGP 9.x: esegui l'upgrade del progetto all'ultima versione di AGP 9.x e risolvi tutti gli avvisi di ritiro esistenti. Una volta
che il tuo progetto funziona con la versione 9.x senza avvisi e senza fare affidamento su
android.newDsl=falseoandroid.builtInKotlin=false, il passaggio alla versione 10.0 sarà una transizione senza problemi. - Controlla i plug-in Gradle di terze parti: assicurati che i plug-in di terze parti
vengano aggiornati alle versioni compatibili con AGP 10.0. I plug-in che si basano ancora su tipi di estensione legacy causeranno errori di build come
ClassCastException: ... cannot be cast to class BaseExtension. - Utilizza le ricette di migrazione ufficiali:per esempi di migrazione complessi e reali e confronti affiancati, consulta il repository GitHub gradle-recipes ufficiale.
Ecco un confronto prima e dopo che mostra come eseguire la migrazione dalle varianti legacy con query eager alla configurazione lazy delle varianti utilizzando androidComponents {}:
Prima: API Variant legacy (rimossa in AGP 10.0)
// Eager evaluation using the legacy Variant API
android {
applicationVariants.all { variant ->
if (variant.buildType.name == "release") {
// Eagerly queries and modifies properties during evaluation
}
}
}
Dopo: API Modern Variant (androidComponents {})
// Lazy, Configuration Cache compatible Variant API
androidComponents {
onVariants(selector().withBuildType("release")) { variant ->
// Safely and lazily configures properties
}
}
Come testare il comportamento di AGP 10.0 in AGP 9.x
Non devi attendere il rilascio di AGP 10.0 per iniziare a testare i comportamenti di build
e convalidare la compatibilità. Durante l'esecuzione su qualsiasi versione di AGP 9.x, puoi applicare esplicitamente il comportamento di AGP 10.0 verificando che il tuo
gradle.properties disattivi qualsiasi disattivazione e imposti i seguenti flag di comportamento
rigidi:
# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true
# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true
Applicando android.newDsl=true e android.builtInKotlin=true, puoi
verificare che la logica di build personalizzata e i plug-in di terze parti siano completamente
compatibili con i rigorosi requisiti API di AGP 10.0.
Disattivazione selettiva dei sottoprogetti durante la migrazione
Se vuoi attivare android.newDsl=true a livello globale nel tuo progetto per
testare i comportamenti moderni, ma hai bisogno di più tempo per eseguire la migrazione di progetti secondari specifici, puoi
disattivare selettivamente i singoli moduli a partire da AGP 9.4.0-alpha04.
Aggiungi android.newDsl.optOut a gradle.properties specificando i percorsi dei progetti:
# Enable modern DSL globally across the build
android.newDsl=true
# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib
Disattivazione selettiva di Kotlin integrato per modulo
Se vuoi attivare Kotlin integrato a livello globale nel tuo progetto
(android.builtInKotlin=true), ma hai bisogno di più tempo per eseguire la migrazione di progetti secondari
specifici da kotlin-android (o per moduli senza codice Kotlin),
configura questi moduli a livello di DSL anziché a livello di progetto. Imposta
enableKotlin = false all'interno del file di build del modulo:
android {
enableKotlin = false
}
Flusso di lavoro per il feedback e la segnalazione di bug
Vogliamo assicurarci che la nuova API Variant supporti i casi d'uso richiesti. Se riscontri un problema durante la migrazione dalle vecchie API in cui la nuova API Variant non può soddisfare il tuo caso d'uso, segui questi passaggi per fornire un feedback:
- Controlla gli elementi esistenti: innanzitutto, controlla il bug di monitoraggio globale dell'API AGP 10.0 Variant per verificare se il blocco della migrazione è già noto e aggiungi +1 al problema.
- Segnala API mancanti:se il tuo caso d'uso è unico, invia una nuova richiesta di funzionalità utilizzando il nostro modello di API Variant specifico in modo che possiamo esaminare la richiesta e aiutarti.
(Provvisorio) L'accesso alle classi AGP interne private viene rimosso
La dipendenza dall'artefatto gradle ora nasconde tutte le classi interne e consente l'accesso alla compilazione solo alle interfacce e alle classi disponibili nell'artefatto gradle-api. Ciò influisce
sulla compilazione
del plug-in.
Non è possibile aggiungere manualmente una dipendenza per accedere alle classi interne.
AGP 9.0 (gennaio 2026)
Le nuove API Variant sono stabili, quelle precedenti sono obsolete
Le API Variant, in fase di incubazione nelle versioni 4.1 e 4.2, sono
stabili e si trovano nell'artefatto gradle-api. Le
interfacce e le classi precedenti utilizzate nella vecchia API Variant sono ora
obsolete e richiedono l'attivazione esplicita per essere utilizzate.
Le nuove interfacce DSL sono stabili, quelle precedenti sono ritirate
Le interfacce DSL che erano in fase di incubazione nelle versioni 4.1, 4.2 e
7.0 sono ora stabili e si trovano nell'artefatto gradle-api. Le interfacce e le classi precedenti utilizzate nel DSL sono ora obsolete e richiedono l'attivazione esplicita per essere utilizzate.
Classi AGP interne private ancora accessibili
Le classi interne private di AGP, che si trovano in altri artefatti, sono ancora accessibili durante la compilazione di file di build e plug-in, ma non consigliamo di utilizzarle perché potrebbero cambiare in modo incompatibile in qualsiasi momento.