Informacje o wersji wtyczki Androida do obsługi Gradle w wersji zapoznawczej

Ta strona zawiera informacje o wersjach próbnych wtyczki Androida do Gradle (AGP).

Wtyczka Androida do obsługi Gradle w wersji 9.0

Wtyczka Androida do obsługi Gradle w wersji 9.0 to nowa wersja główna AGP, która wprowadza zmiany w interfejsie API i zachowaniu.

Aby zaktualizować wtyczkę Androida do obsługi Gradle do wersji 9.0.0-alpha10, użyj Asystenta uaktualniania wtyczki Androida do obsługi Gradle w Android Studio Otter | 2025.2.1.

Asystent uaktualniania AGP pomaga zachować dotychczasowe zachowania podczas uaktualniania projektu, gdy jest to odpowiednie. Umożliwia to uaktualnienie projektu do AGP 9.0, nawet jeśli nie chcesz jeszcze stosować wszystkich nowych ustawień domyślnych w AGP 9.0.

Zgodność

Maksymalny poziom interfejsu Android API obsługiwany przez wtyczkę Androida do Gradle w wersji 9.0.0-alpha10 to poziom 36.

Wtyczka Androida do obsługi Gradle w wersji 9.0.0-alpha10 wymaga Gradle w wersji 9.0.0.

Klasy android DSL implementują teraz tylko nowe interfejsy publiczne.

W ciągu ostatnich kilku lat wprowadziliśmy nowe interfejsy dla naszego języka DSL i interfejsu API, aby lepiej kontrolować, które interfejsy API są publiczne. Wersje AGP 7.x i 8.x nadal używały starych typów DSL (np. BaseExtension), które również implementowały nowe interfejsy publiczne, aby zachować zgodność w trakcie prac nad interfejsami.

AGP 9.0 korzysta wyłącznie z naszych nowych interfejsów DSL, a implementacje zostały zmienione na nowe typy, które są w pełni ukryte. Ta zmiana usuwa też dostęp do starego, wycofanego interfejsu API wariantów.

Aby zaktualizować AGP do wersji 9.0, może być konieczne wykonanie tych czynności:

• Sprawdź, czy projekt jest zgodny z wbudowanym Kotlinem: wtyczka org.jetbrains.kotlin.android nie jest zgodna z nowym DSL.

• Przełącz projekty KMP na wtyczkę Android Gradle Library Plugin for KMP: używanie wtyczki org.jetbrains.kotlin.multiplatform w tym samym podprojekcie Gradle co wtyczki com.android.library i com.android.application jest niezgodne z nowym DSL.

• Zaktualizuj pliki kompilacji: zmiana interfejsów ma na celu zachowanie jak największego podobieństwa do DSL, ale mogą wystąpić niewielkie zmiany.

• Zaktualizuj niestandardową logikę kompilacji, aby odwoływała się do nowego języka DSL i interfejsu API: zastąp wszystkie odwołania do wewnętrznego języka DSL interfejsami publicznego języka DSL. W większości przypadków będzie to zamiana 1:1. Zastąp wszystkie użycia interfejsu applicationVariants i podobnych interfejsów API nowym androidComponents. Może to być bardziej skomplikowane, ponieważ interfejs androidComponents API został zaprojektowany tak, aby był bardziej stabilny i zapewniał dłuższą zgodność wtyczek. Przykłady znajdziesz w przepisach Gradle.

• Zaktualizuj wtyczki innych firm: niektóre wtyczki innych firm mogą nadal korzystać z interfejsów lub interfejsów API, które nie są już udostępniane. Przejdź na wersje tych wtyczek, które są zgodne z AGP 9.0.

Przejście na nowe interfejsy DSL uniemożliwia wtyczkom i skryptom kompilacji Gradle korzystanie z różnych wycofanych interfejsów API, w tym:

androidComponents {
    onVariants() { variant ->
        variant.signingConfig
            .enableV1Signing.set(false)
    }
}

androidComponents {
    beforeVariants(
        selector()
            .withBuildType("debug")
            .withFlavor("color", "blue")
    ) { variantBuilder ->
        variantBuilder.enable = false
    }
  }

Jeśli po zaktualizowaniu do AGP 9.0 zobaczysz ten komunikat o błędzie, oznacza to, że Twój projekt nadal odwołuje się do niektórych starych typów:

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

Jeśli blokują Cię niekompatybilne wtyczki innych firm, możesz zrezygnować z nich i przywrócić stare implementacje DSL oraz stary interfejs API wariantów. W tym czasie nowe interfejsy są również dostępne i nadal możesz zaktualizować własną logikę kompilacji do nowego interfejsu API. Aby zrezygnować, umieść ten wiersz w pliku gradle.properties:

android.newDsl=false

Możesz też rozpocząć uaktualnianie do nowych interfejsów API przed uaktualnieniem do AGP 9.0. Nowe interfejsy są dostępne w wielu wersjach AGP, więc możesz mieć połączenie nowych i starych. W dokumentacji referencyjnej interfejsu AGP API znajdziesz informacje o interfejsie API dla każdej wersji AGP oraz daty dodania poszczególnych klas, metod i pól.

W fazie alfa wersji 9.0 będziemy kontaktować się z autorami wtyczek, aby pomóc im dostosować i opublikować wtyczki w pełni zgodne z nowymi trybami. Ulepszymy też Asystenta uaktualniania AGP w Android Studio, aby przeprowadzić Cię przez proces migracji.

Jeśli zauważysz, że w nowym interfejsie DSL lub Variant API brakuje funkcji, jak najszybciej zgłoś problem.

Wbudowany Kotlin

Wtyczka Androida do obsługi Gradle w wersji 9.0 ma wbudowaną obsługę kompilacji w języku Kotlin, która zastępuje oddzielnie stosowaną wtyczkę Kotlin. Upraszcza to integrację z AGP, pozwala uniknąć korzystania z wycofanych interfejsów API i w niektórych przypadkach zwiększa wydajność.

Wtyczka Androida do obsługi Gradle w wersji 9.0 ma zależność środowiska wykonawczego od wtyczki Kotlin Gradle w wersji 2.2.10, która jest minimalną wersją wymaganą do obsługi wbudowanego języka Kotlin.

Wbudowany język Kotlin w AGP 9.0 zapewnia pełną obsługę środowiska IDE Android Studio dla test-fixtures. Aby to zrobić, użyj AGP w wersji 9.0.0-alpha07 lub nowszej.

Możesz zrezygnować z wbudowanego języka Kotlin, ustawiając android.builtInKotlin=false.

Jeśli zrezygnowano z wbudowanego języka Kotlin i trzeba używać starszej wersji wtyczki Kotlin Gradle, można wymusić przejście na starszą wersję:

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

Zmiany w działaniu

Wtyczka Androida do obsługi Gradle w wersji 9.0 ma te nowe funkcje:

AGP 9.0 zawiera aktualizacje domyślnych wartości tych właściwości Gradle. Dzięki temu podczas uaktualniania możesz zachować działanie AGP 8.13:

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

Usunięte funkcje

Wtyczka Androida do obsługi Gradle w wersji 9.0 usuwa te funkcje:

• Obsługa umieszczonych aplikacji na Wear OS
  AGP 9.0 usuwa obsługę umieszczania aplikacji na Wear OS, która nie jest już obsługiwana w Google Play. Obejmuje to usunięcie konfiguracji wearApp i AndroidSourceSet.wearAppConfigurationName DSL. Więcej informacji o publikowaniu aplikacji na Wear OS znajdziesz w artykule Dystrybucja aplikacji na Wear OS.
• androidDependencies i sourceSets zgłosić zadanie

Zmieniony DSL

Wtyczka Androida do obsługi Gradle w wersji 9.0 zawiera te zmiany powodujące niezgodność w języku DSL:

• Parametryzacja funkcji CommonExtension została usunięta.

  Sama w sobie jest to tylko zmiana powodująca niezgodność na poziomie źródła, która ma pomóc uniknąć takich zmian w przyszłości. Oznacza to jednak również, że metody blokowania muszą zostać przeniesione z CommonExtension do ApplicationExtension, LibraryExension, DynamicFeatureExtension i TestExtension.

  Podczas uaktualniania projektu do AGP 9.0 zmień kod wtyczki Gradle, który korzysta z tych parametrów lub metod blokowych. Na przykład ten wtyczka została zaktualizowana, aby usunąć parametr typu i nie korzystać z usuniętych metod blokowania:

  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)
          }
      }
  }
  

  W przypadku wtyczek, które są przeznaczone dla zakresu wersji AGP, bezpośrednie użycie funkcji pobierającej jest binarne zgodne z wersjami AGP starszymi niż 9.0.

Usunięto DSL

Wtyczka Androida do obsługi Gradle w wersji 9.0 usuwa:

• AndroidSourceSet.jni, ponieważ nie działał.

• AndroidSourceSet.wearAppConfigurationName, ponieważ dotyczy to usuniętej obsługi wbudowanej aplikacji na Wear OS.

• BuildType.isRenderscriptDebuggable, ponieważ nie działał.

• DependencyVariantSelection. Zastępuje ją element DependencySelection, który jest udostępniany jako kotlin.android.localDependencySelection.

• Installation.installOptions(String). Zastępuje ją modyfikowalna właściwość Installation.installOptions.

• Blok PostProcessing, który jest eksperymentalny i nigdy nie został ustabilizowany.

• ProductFlavor.setDimension, która jest zastępowana przez właściwość dimension

• LanguageSplitOptions, która była przydatna tylko w przypadku aplikacji błyskawicznych w Google Play, które zostały wycofane.

Usunięte interfejsy API

Wtyczka Androida do obsługi Gradle w wersji 9.0 usuwa:

• AndroidComponentsExtension.finalizeDSl. Zastępuje ją finalizeDsl

• Component.transformClassesWith. Zastępuje ją Instrumentation.transformClassesWith

• Component.setAsmFramesComputationMode. Zastępuje ją Instrumentation.setAsmFramesComputationMode

• ComponentBuilder.enabled. Zastępuje ją ComponentBuilder.enable.

• DependenciesInfoBuilder.includedInApk. Zastąpienie:includeInApk

• DependenciesInfoBuilder.includedInBundle. Zastąpienie:includeInBundle

• GeneratesApk.targetSdkVersion. Zastąpiono ją wartością targetSdk

• Variant.minSdkVersion. Zastąpiono ją wartością minSdk

• Variant.maxSdkVersion. Zastąpiono ją wartością maxSdk

• Variant.targetSdkVersion. Zastąpiono ją wartością targetSdk

• Variant.unitTest, ponieważ nie dotyczyło to wtyczki com.android.test. unitTest jest dostępna w przypadku podtypów VariantBuilder rozszerzających HasUnitTest.

• VariantBuilder.targetSdk i targetSdkPreview, ponieważ nie miały one znaczenia w bibliotekach. Zamiast niej użyj właściwości GeneratesApkBuilder.targetSdk lub GeneratesApkBuilder.targetSdkPreview.

• VariantBuilder.enableUnitTest, ponieważ nie dotyczyło to wtyczki com.android.test. enableUnitTest jest dostępna w przypadku podtypów VariantBuilder rozszerzających HasUnitTestBuilder.

• Typ VariantBuilder.unitTestEnabled został usunięty na rzecz bardziej spójnie nazwanego typu enableUnitTest w przypadku podtypów VariantBuilder rozszerzających typ HasUnitTestBuilder.

• VariantOutput.enable. Zastąpiono ją wartością enabled

• Wycofane i wyłączone funkcje FeaturePlugin i FeatureExtension.

• Wycofane i wyłączone interfejsy APIBaseExtension.registerTransform, które były dostępne tylko po to, aby umożliwić kompilowanie pod kątem najnowszej wersji AGP przy jednoczesnym kierowaniu na AGP 4.2 lub starszą.

Usunięte właściwości Gradle

Poniższe właściwości Gradle zostały początkowo dodane jako sposoby globalnego wyłączania funkcji, które były domyślnie włączone.

Te funkcje są domyślnie wyłączone od wersji AGP 8.0 lub starszej. Włącz te funkcje tylko w podprojektach, które ich używają, aby zwiększyć wydajność kompilacji.

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

Wymuszane właściwości Gradle

AGP 9.0 zgłasza błąd, jeśli ustawisz te właściwości Gradle.

Asystent uaktualniania wtyczki Androida do obsługi Gradle nie uaktualni projektów do AGP 9.0, które korzystają z tych właściwości.

Rozwiązane problemy

Wtyczka Androida do obsługi Gradle w wersji 9.0.0-alpha10

Wtyczka Androida do obsługi Gradle w wersji 9.0.0-alpha09

Wtyczka Androida do obsługi Gradle w wersji 9.0.0-alpha08

Wtyczka Androida do obsługi Gradle w wersji 9.0.0-alpha07

Wtyczka Androida do obsługi Gradle w wersji 9.0.0-alpha06

Wtyczka Androida do obsługi Gradle w wersji 9.0.0-alpha05

Wtyczka Androida do obsługi Gradle w wersji 9.0.0-alpha04

Wtyczka Androida do obsługi Gradle w wersji 9.0.0-alpha03

Wtyczka Androida do obsługi Gradle w wersji 9.0.0-alpha02

Wtyczka Androida do obsługi Gradle w wersji 9.0.0-alpha01