Note di rilascio dell'anteprima del plug-in Android per Gradle

Questa pagina contiene le note di rilascio per le versioni di anteprima del plug-in Android Gradle (AGP).

Plug-in Android per Gradle 9.0

Il plug-in Android per Gradle 9.0 è una nuova versione principale di AGP e introduce modifiche al comportamento e alle API.

Per eseguire l'aggiornamento al plug-in Android per Gradle 9.0.0-alpha10, utilizza l'assistente per l'upgrade del plug-in Android per Gradle in Android Studio Otter | 2025.2.1.

L'assistente per l'upgrade di AGP aiuta a preservare i comportamenti esistenti durante l'upgrade del progetto, se appropriato, consentendoti di eseguire l'upgrade del progetto per utilizzare AGP 9.0, anche se non sei pronto ad adottare tutti i nuovi valori predefiniti di AGP 9.0.

Compatibilità

Il livello API Android massimo supportato da Android Gradle Plugin 9.0.0-alpha10 è il livello API 36.

Il plug-in Android per Gradle 9.0.0-alpha10 richiede Gradle 9.0.0.

Versione minima Versione predefinita Note
Gradle 9.0.0 9.0.0 Per scoprire di più, consulta la sezione Aggiornare Gradle.
Strumenti di compilazione SDK 36.0.0 36.0.0 Installa o configura gli strumenti di creazione dell'SDK.
NDK N/D 28.2.13676358 Installa o configura una versione diversa dell'NDK.
JDK 17 17 Per saperne di più, vedi Impostare la versione di JDK.

Le classi android DSL ora implementano solo le nuove interfacce pubbliche

Negli ultimi anni abbiamo introdotto nuove interfacce per il nostro DSL e la nostra API per controllare meglio quali API sono pubbliche. Le versioni di AGP 7.x e 8.x utilizzavano ancora i vecchi tipi di DSL (ad esempio BaseExtension), che implementavano anche le nuove interfacce pubbliche, per mantenere la compatibilità man mano che il lavoro sulle interfacce procedeva.

AGP 9.0 utilizza esclusivamente le nostre nuove interfacce DSL e le implementazioni sono state modificate in nuovi tipi completamente nascosti. Queste modifiche rimuovono anche l'accesso alla vecchia API variante deprecata.

Per eseguire l'aggiornamento ad AGP 9.0, potresti dover:

  • Assicurati che il tuo progetto sia compatibile con Kotlin integrato: il plug-in org.jetbrains.kotlin.android non è compatibile con il nuovo DSL.

  • Passa ai progetti KMP con il plug-in Android Gradle Library per KMP: l'utilizzo del plug-in org.jetbrains.kotlin.multiplatform nello stesso sottoprogetto Gradle dei plug-in com.android.library e com.android.application non è compatibile con il nuovo DSL.

  • Aggiorna i file di build: Sebbene la modifica delle interfacce sia pensata per mantenere la DSL il più simile possibile, potrebbero esserci alcune piccole modifiche.

  • Aggiorna la logica di build personalizzata in modo che faccia riferimento alla nuova DSL e alla nuova API: Sostituisci tutti i riferimenti alla DSL interna con le interfacce DSL pubbliche. Nella maggior parte dei casi, si tratta di una sostituzione uno a uno. Sostituisci qualsiasi utilizzo di applicationVariants e API simili con la nuova API androidComponents. Questa operazione potrebbe essere più complessa, in quanto l'API androidComponents è progettata per essere più stabile e mantenere la compatibilità dei plug-in più a lungo. Consulta le nostre ricette Gradle per alcuni esempi.

  • Aggiorna i plug-in di terze parti: alcuni plug-in di terze parti potrebbero ancora dipendere da interfacce o API non più esposte. Esegui la migrazione alle versioni di questi plug-in compatibili con AGP 9.0.

Il passaggio alle nuove interfacce DSL impedisce ai plug-in e agli script di build Gradle di utilizzare varie API ritirate, tra cui:

API obsoleta nel blocco android Funzione Sostituzione
applicationVariants,
libraryVariants,
testVariants e
unitTestVariants 		Punti di estensione per i plug-in per aggiungere nuove funzionalità ad AGP. Sostituisci questo valore con l'API androidComponents.onVariants, ad esempio: 
androidComponents {
    onVariants() { variant ->
        variant.signingConfig
            .enableV1Signing.set(false)
    }
}
 Potrebbe non esistere una sostituzione diretta per tutte le API precedenti. Segnala un problema se esiste un caso d'uso non coperto dalle nuove API per le varianti.
variantFilter Consente di disattivare le varianti selezionate. Sostituisci questo valore con l'API androidComponents.beforeVariants, ad esempio: 
androidComponents {
    beforeVariants(
        selector()
            .withBuildType("debug")
            .withFlavor("color", "blue")
    ) { variantBuilder ->
        variantBuilder.enable = false
    }
  }
deviceProvider e
testServer 		Registrazione di ambienti di test personalizzati per l'esecuzione di test su dispositivi ed emulatori Android. Passa a Dispositivi gestiti da Gradle.
sdkDirectory,
ndkDirectory,
bootClasspath,
adbExecutable e
adbExe 		Utilizzo di vari componenti dell'SDK Android per attività personalizzate. Passa a androidComponents.sdkComponents.
registerArtifactType,
registerBuildTypeSourceProvider,
registerProductFlavorSourceProvider,
registerJavaArtifact,
registerMultiFlavorSourceProvider e
wrapJavaSourceSet		 Funzionalità obsolete per lo più correlate alla gestione delle sorgenti generate in Android Studio, che hanno smesso di funzionare in AGP 7.2.0. Non esiste un'alternativa diretta a queste API.

Se esegui l'aggiornamento ad AGP 9.0 e visualizzi il seguente messaggio di errore, significa che il tuo progetto fa ancora riferimento ad alcuni dei tipi precedenti:

java.lang.ClassCastException: class com.android.build.gradle.internal.dsl.ApplicationExtensionImpl$AgpDecorated_Decorated
cannot be cast to class com.android.build.gradle.BaseExtension

Se sei bloccato da plug-in di terze parti incompatibili, puoi disattivare le vecchie implementazioni per DSL, nonché la vecchia API Variant. Durante questa operazione, sono disponibili anche le nuove interfacce e puoi comunque aggiornare la tua logica di build alla nuova API. Per effettuare la disattivazione, includi questa riga nel file gradle.properties:

android.newDsl=false

Puoi anche iniziare l'upgrade alle nuove API prima di eseguire l'upgrade ad AGP 9.0. Le nuove interfacce sono presenti in molte versioni di AGP, quindi puoi avere un mix di nuove e vecchie. La documentazione di riferimento dell'API AGP mostra la superficie dell'API per ogni versione di AGP e quando sono stati aggiunti ogni classe, metodo e campo.

Durante la fase alpha 9.0, contatteremo gli autori di plug-in per aiutarli ad adattare e rilasciare plug-in completamente compatibili con le nuove modalità e miglioreremo l'assistente per l'upgrade di AGP in Android Studio per guidarti durante la migrazione.

Se riscontri che le nuove API DSL o Variant non dispongono di funzionalità o caratteristiche, segnala un problema il prima possibile.

Kotlin integrato

Il plug-in Android per Gradle 9.0 include il supporto integrato per la compilazione di Kotlin, sostituendo il plug-in Kotlin applicato separatamente. Ciò semplifica l'integrazione con AGP, evitando l'utilizzo delle API ritirate e migliorando le prestazioni in alcuni casi.

Il plug-in Android per Gradle 9.0 ha una dipendenza di runtime dal plug-in Kotlin Gradle 2.2.10, che è la versione minima richiesta per il supporto Kotlin integrato.

Kotlin integrato in AGP 9.0 offre il supporto completo dell'IDE Android Studio per test-fixtures. Per provare questa funzionalità, utilizza AGP 9.0.0-alpha07 o versioni successive.

Puoi disattivare Kotlin integrato impostando android.builtInKotlin=false.

Se hai disattivato Kotlin integrato e devi anche utilizzare una versione precedente del plug-in Kotlin Gradle, puoi forzare il downgrade:

buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("2.0.0") } // or another version that you want to use
        }
    }
}

Modifiche al funzionamento

Il plug-in Android per Gradle 9.0 ha i seguenti nuovi comportamenti:

Comportamento Consiglio
Il plug-in Android per Gradle 9.0 utilizza la versione r28c dell'NDK per impostazione predefinita. Valuta la possibilità di specificare in modo esplicito la versione dell'NDK che vuoi utilizzare.
Il plug-in Android Gradle 9.0 richiede per impostazione predefinita che i consumatori di una libreria utilizzino la stessa versione dell'SDK di compilazione o una versione successiva. Utilizza lo stesso SDK di compilazione o una versione successiva quando utilizzi una libreria. Se non è possibile o vuoi dare più tempo ai consumatori di una libreria che pubblichi per passare, imposta AarMetadata.minCompileSdk in modo esplicito.

AGP 9.0 include aggiornamenti ai valori predefiniti delle seguenti proprietà di Gradle. In questo modo, puoi scegliere di mantenere il comportamento di AGP 8.13 durante l'upgrade:

Proprietà Funzione Passaggio da AGP 8.13 ad AGP 9.0 Consiglio
android.newDsl Utilizza le nuove interfacce DSL senza esporre le implementazioni legacy del blocco android.
Ciò significa anche che l'API legacy per le varianti, ad esempio android.applicationVariants non è più accessibile. 		false → true Puoi disattivare l'opzione impostando android.newDsl=false.
Una volta che tutti i plug-in e la logica di build utilizzati dal tuo progetto sono compatibili, rimuovi l'opt-out.
android.builtInKotlin È stato attivato il supporto per la compilazione del codice Kotlin direttamente nel plug-in Android Gradle, senza il plug-in org.jetbrains.kotlin.android. false → true Adotta Kotlin integrato rimuovendo l'utilizzo del plug-in org.jetbrains.kotlin.android, se possibile. In caso contrario, disattiva l'opzione impostando android.builtInKotlin=false
android.uniquePackageNames Impone che ogni libreria abbia un nome di pacchetto distinto. false → true Specifica nomi di pacchetti univoci per tutte le librerie all'interno del progetto. Se non è possibile, puoi disattivare questo flag durante la migrazione.
android.dependency.useConstraints Controlla l'utilizzo dei vincoli di dipendenza tra le configurazioni.
Il valore predefinito in AGP 9.0 è false, che utilizza solo i vincoli nei test dei dispositivi dell'applicazione (AndroidTest). Se imposti questo valore su true, verrà ripristinato il comportamento della versione 8.13. 		true → false Non utilizzare vincoli di dipendenza ovunque, a meno che non siano necessari. L'accettazione del nuovo valore predefinito di questo flag consente anche le ottimizzazioni nel processo di importazione del progetto, che dovrebbe ridurre il tempo di importazione per le build con molti progetti secondari della libreria Android.
aandroid.enableAppCompileTimeRClass Compila il codice nelle applicazioni in base a una classe R non finale, allineando la compilazione delle applicazioni a quella delle librerie.
Ciò migliora l'incrementalità e apre la strada a future ottimizzazioni delle prestazioni del flusso di elaborazione delle risorse. 		false → true Molti progetti possono semplicemente adottare il nuovo comportamento senza modifiche al codice sorgente. Se i campi della classe R vengono utilizzati in un punto che richiede una costante, ad esempio i casi switch, esegui il refactoring per utilizzare istruzioni if concatenate.
android.sdk.defaultTargetSdkToCompileSdkIfUnset Utilizza la versione dell'SDK di compilazione come valore predefinito per la versione dell'SDK target in app e test.
Prima di questa modifica, la versione dell'SDK target veniva impostata per impostazione predefinita sulla versione dell'SDK minima. 		false → true Specifica esplicitamente la versione dell'SDK target per app e test.
android.onlyEnableUnitTestForTheTestedBuildType Crea solo componenti di test delle unità per il tipo di build testato.
Nel progetto predefinito, questo comporta un singolo test unitario per il debug, mentre il comportamento precedente prevedeva l'esecuzione di test unitari per il debug o il rilascio. 		false → true Se il tuo progetto non richiede l'esecuzione di test sia per il debug che per il rilascio, non è necessaria alcuna modifica.
android.proguard.failOnMissingFiles La build non riesce e viene visualizzato un errore se uno dei file di conservazione specificati nel DSL AGP non esiste sul disco. Prima di questa modifica, gli errori di battitura nei nomi dei file comportavano l'ignoramento silenzioso dei file. false → true Rimuovi eventuali dichiarazioni di file Proguard non validi
android.r8.optimizedResourceShrinking Consente a R8 di conservare meno risorse Android considerando insieme classi e risorse Android. false → true Se le regole di conservazione del progetto sono già state completate, non è necessaria alcuna modifica.
android.r8.strictFullModeForKeepRules Consente a R8 di conservare meno elementi non conservando implicitamente il costruttore predefinito quando una classe viene conservata. ovvero -keep class A non implica più -keep class A { <init>(); }
 false → true Se le regole di conservazione del progetto sono già state completate, non è necessaria alcuna modifica.

Sostituisci -keep class A con -keep class A { <init>(); } nelle regole di conservazione del progetto per tutti i casi in cui è necessario conservare il costruttore predefinito.
android.defaults.buildfeatures.resvalues Attiva resValues in tutti i progetti secondari true → false Attiva resValues solo nei sottoprogetti che ne hanno bisogno impostando quanto segue nei file di build Gradle di questi progetti: 
android {
  buildFeatures {
    resValues = true
  }
}
android.defaults.buildfeatures.shaders Attiva la compilazione degli shader in tutti i sottoprogetti true → false Attiva la compilazione degli shader solo nei sottoprogetti che contengono shader da compilare impostando quanto segue nei file di build Gradle di questi progetti: 
android {
  buildFeatures {
    shaders = true
  }
}
android.r8.proguardAndroidTxt.disallowed In AGP 9.0, getDefaultProguardFile() supporterà solo proguard-android-optimize.txt anziché proguard-android.txt. Questo per evitare l'utilizzo accidentale del flag ­dontoptimize, incluso in proguard-android.txt. false → true Puoi specificare esplicitamente ­dontoptimize in un file proguard personalizzato se vuoi evitare l'ottimizzazione, oltre a utilizzare proguard-android-optimize.txt. Se possibile, rimuovi il flag ­dontoptimize da questo file, in quanto riduce i vantaggi dell'ottimizzazione R8. In caso contrario, disattiva l'opzione impostando android.r8.globalOptionsInConsumerRules.disallowed=false.
android.r8.globalOptionsInConsumerRules.disallowed A partire da AGP 9.0, la pubblicazione di librerie e moduli di funzionalità Android non andrà a buon fine se i file keep per i consumatori contengono configurazioni Proguard problematiche. I file di conservazione dei consumatori che includono opzioni globali come ­dontoptimize o ­dontobfuscate devono essere utilizzati solo nei moduli dell'applicazione e possono ridurre i vantaggi dell'ottimizzazione per gli utenti della libreria. La compilazione del modulo dell'app per Android ignorerà automaticamente qualsiasi opzione globale di questo tipo se incorporata in una dipendenza precompilata (JAR o AAR). Puoi vedere quando si verifica questo problema controllando configuration.txt (in genere in un percorso come <app_module>/build/outputs/mapping/<build_variant>/configuration.txt) per commenti come: # REMOVED CONSUMER RULE: ­dontoptimize false → true Le raccolte pubblicate devono rimuovere le regole incompatibili. Le librerie interne devono spostare le regole incompatibili ma necessarie in un file proguardFile in un modulo dell'app. Disattiva l'opzione impostando android.r8.globalOptionsInConsumerRules.disallowed=false. Una volta che tutti i tuoi file di Keep per i consumatori sono compatibili, rimuovi l'opt-out.

Funzionalità rimosse

Il plug-in Android per Gradle 9.0 rimuove le seguenti funzionalità:

DSL modificato

Il plug-in Android per Gradle 9.0 presenta le seguenti modifiche DSL che causano interruzioni:

  • La parametrizzazione di CommonExtension è stata rimossa.

    Di per sé, questa è solo una modifica che causa interruzioni a livello di origine per evitare future modifiche che causano interruzioni a livello di origine, ma significa anche che i metodi di blocco devono passare da CommonExtension a ApplicationExtension, LibraryExension, DynamicFeatureExtension e TestExtension.

    Quando esegui l'upgrade del progetto ad AGP 9.0, esegui il refactoring del codice del plug-in Gradle che utilizza questi parametri o i metodi di blocco. Ad esempio, il seguente plug-in viene aggiornato per rimuovere il parametro type e non fare affidamento sui metodi di blocco rimossi:

    AGP 8.13

    val commonExtension: CommonExtension<*, *, *, *, *, *> =
        extensions.getByType(CommonExtension::class)
commonExtension.apply {
    defaultConfig {
        minSdk {
            version = release(28)
        }
    }
}

    AGP 9.0

    val commonExtension: CommonExtension =
        extensions.getByType(CommonExtension::class)
commonExtension.apply {
    defaultConfig.apply {
        minSdk {
            version = release(28)
        }
    }
}

    Per i plug-in che hanno come target un intervallo di versioni di AGP, l'utilizzo diretto del getter è compatibile a livello binario con le versioni di AGP precedenti alla 9.0.

DSL rimosso

Il plug-in Android per Gradle 9.0 rimuove:

API rimosse

Il plug-in Android per Gradle 9.0 rimuove:

Proprietà Gradle rimosse

Le seguenti proprietà Gradle sono state inizialmente aggiunte come modi per disattivare globalmente le funzionalità abilitate per impostazione predefinita.

Queste funzionalità sono disattivate per impostazione predefinita a partire da AGP 8.0 o versioni precedenti. Attiva queste funzionalità solo nei sottoprogetti che le utilizzano per una compilazione più efficiente.

Proprietà Funzione Sostituzione
android.defaults.buildfeatures.aidl Attiva la compilazione AIDL in tutti i progetti secondari Attiva la compilazione AIDL solo nei sottoprogetti in cui sono presenti origini AIDL impostando la seguente proprietà nei file di build Gradle di questi progetti: 
android {
  buildFeatures {
    aidl = true
  }
}
 nel file di build Gradle di ogni progetto secondario contenente origini AIDL
android.defaults.buildfeatures.renderscript Attiva la compilazione di RenderScript in tutti i progetti secondari Attiva la compilazione di renderscript solo nei sottoprogetti in cui sono presenti origini renderscript impostando la seguente proprietà nei file di build Gradle di questi progetti: 
android {
  buildFeatures {
    renderScript = true
  }
}

Proprietà Gradle applicate

AGP 9.0 genera un errore se imposti le seguenti proprietà Gradle.

L'assistente per l'upgrade del plug-in Android per Gradle non eseguirà l'upgrade dei progetti ad AGP 9.0 che utilizzano queste proprietà.

Proprietà Funzione
android.r8.integratedResourceShrinking La riduzione delle risorse ora viene sempre eseguita nell'ambito di R8. L'implementazione precedente è stata rimossa.

Problemi risolti

Plug-in Android per Gradle 9.0.0-alpha10

Problemi risolti
Plug-in Android per Gradle
extractNativeLibs e useEmbeddedDex non devono provenire dal manifest
Avvisi di R8 in AGP 9.0.0-alpha09
Pelucchi
Kotlin integrato non aggiunge .kotlin_module a META-INF
Il classpath di Lint contiene classi duplicate in versioni diverse
Soluzione alternativa per l'override delle risorse private non funzionante (tools:override = "true")

Plug-in Android per Gradle 9.0.0-alpha09

Problemi risolti
Plug-in Android per Gradle
Il plug-in `legacy-kapt` salta l'elaborazione delle annotazioni a differenza di `kotlin-kapt`
compileSdkSpec.minorApiLevel non funziona con SettingsExtension
[fused lib - public] Generated fused library does not include sources

Plug-in Android per Gradle 9.0.0-alpha08

Problemi risolti
Nessun problema pubblico è stato contrassegnato come risolto in AGP 9.0.0-alpha08

Plug-in Android per Gradle 9.0.0-alpha07

Problemi risolti
Plug-in Android per Gradle
Una build non riesce se sono presenti attività di generazione del codice
Con `android.builtInKotlin=false`, `android.newDsl=false` e `android.enableLegacyVariantApi=false`, l'utilizzo del plug-in `kotlin-android` non andrà a buon fine e verrà visualizzato il messaggio "API 'applicationVariants' is obsolete" (l'API "applicationVariants" è obsoleta).
Kotlin integrato non riesce a risolvere kotlin-stdlib senza versione quando kotlin.stdlib.default.dependency=false
DexData apre un file senza chiuderlo, impedendo la pulizia
AndroidSourceDirectorySet deve smettere di estendere PatternFilterable in AGP 9.0
Errore di test fixture nei moduli di solo test
Errore errato durante l'utilizzo dei ricevitori di contesto nei test fixture
Errori IDE errati per il codice Kotlin in testFixtures

Plug-in Android per Gradle 9.0.0-alpha06

Problemi risolti
Plug-in Android per Gradle
Il nuovo DSL di ottimizzazione non crea configuration.txt per impostazione predefinita
AGP 8.13.0 non riesce a verificare il grafico di navigazione in un modulo
AGP utilizza l'API Gradle deprecata: notazione multi-stringa
Avvisa gli utenti che tentano di utilizzare la libreria multidex precedente con minSdkVersion >=21
Pelucchi
Lint ChecksSdkIntAtLeast non verifica se il valore annotato è corretto

Plug-in Android per Gradle 9.0.0-alpha05

Problemi risolti
Plug-in Android per Gradle
android.proguard.failOnMissingFiles non funziona per consumerProguardFiles
Aggiorna la dipendenza del plug-in Kotlin Gradle alla versione 2.2.10
Crea KotlinJvmAndroidCompilation utilizzando l'API KGP
Modalità API esplicita Kotlin applicata alle origini di test
Pelucchi
Lint genera l'avviso "Could not clean up K2 caches"

Plug-in Android per Gradle 9.0.0-alpha04

Problemi risolti
Plug-in Android per Gradle
Passaggio dalla versione Java 8 alla versione Java 11 predefinita di origine/destinazione in AGP 9.0
Flip android.useAndroidX default to true
Gestione migliore delle eccezioni quando si applica il plug-in kapt con Kotlin integrato.
Pelucchi
Lint genera l'avviso "Could not clean up K2 caches"

Plug-in Android per Gradle 9.0.0-alpha03

Problemi risolti
Plug-in Android per Gradle
Quando `isIncludeAndroidResources` è attivato, `process{Variant}UnitTestManifest` non riesce a unire gli utilizzi di tools:overrideLibrary in AGP 8.12.0
AGP che causa avvisi di ritiro in Gradle per le attività di test JVM
DependencyReportTask non è compatibile con la cache di configurazione
Pelucchi
Bug: la rimozione delle risorse inutilizzate non rimuove anche le relative traduzioni e non viene chiesto nulla al riguardo

Plug-in Android per Gradle 9.0.0-alpha02

Problemi risolti
Plug-in Android per Gradle
Errore di compilazione quando il file Proguard non esiste
rimuovere i flag gradle.properties predefiniti di buildconfig
Modificare il valore predefinito di targetSdk dell'app in modo che si basi su compileSdk anziché su minSdk

Plug-in Android per Gradle 9.0.0-alpha01

Problemi risolti
Plug-in Android per Gradle
Rimozione di AndroidSourceSet.jni ritirato in AGP 9.0
Rimozione di Installation.installOptions() in AGP 9.0
Rimuovi BuildType.isRenderscriptDebuggable in AGP 9.0.
Rimuovere android.defaults.buildfeatures.renderscript
`com.android.kotlin.multiplatform.library` si arresta in modo anomalo con i dispositivi gestiti da Gradle
Rimuovi i flag gradle.properties predefiniti di `android.defaults.buildfeatures.aidl`