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

Ta strona zawiera informacje o wersjach testowych 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-beta04, użyj asystenta uaktualniania wtyczki Androida do obsługi Gradle w pakiecie nowych funkcji Android Studio Otter 3 | 2025.2.3.

Asystent uaktualniania AGP pomaga zachować dotychczasowe działanie projektu podczas uaktualniania, 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-beta04 to poziom 36.

Wtyczka Androida do obsługi Gradle w wersji 9.0.0-beta04 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. Wtyczki AGP w wersjach 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.

Wtyczka Androida do obsługi Gradle 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. Spowoduje to również usunięcie dostępu do starego, wycofanego interfejsu API wariantu.

Aby zaktualizować wtyczkę Androida do obsługi Gradle do wersji 9.0, może być konieczne wykonanie tych czynności:

• Upewnij się, że 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 wymiana 1:1. Zastąp wszystkie użycia interfejsów API applicationVariants i podobnych nowym androidComponents API. 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 uaktualnieniu do AGP 9.0 zobaczysz ten komunikat o błędzie, oznacza to, że 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ą też dostępne i nadal możesz zaktualizować własną logikę kompilacji do nowego interfejsu API. Aby zrezygnować, umieść w pliku gradle.properties ten wiersz:

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 kontaktujemy 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 lub możliwości, jak najszybciej zgłoś problem.

Wbudowany język Kotlin

Wtyczka Androida do obsługi Gradle w wersji 9.0 wprowadza wbudowaną obsługę języka Kotlin i domyślnie ją włącza. Oznacza to, że nie musisz już stosować wtyczki org.jetbrains.kotlin.android (ani kotlin-android) w plikach kompilacji, aby kompilować pliki źródłowe Kotlin. Upraszcza to integrację Kotlina z AGP, pozwala uniknąć używania wycofanych interfejsów API i w niektórych przypadkach zwiększa wydajność.

Dlatego po uaktualnieniu projektu do AGP 9.0 musisz też przeprowadzić migrację na wbudowany język Kotlin lub zrezygnować.

Możesz też wybiórczo wyłączyć wbudowaną obsługę języka Kotlin w podprojektach Gradle, które nie zawierają źródeł w tym języku.

Zależność w czasie działania od wtyczki Kotlin Gradle

Aby zapewnić obsługę wbudowanego języka Kotlin, wtyczka Androida do obsługi Gradle w wersji 9.0 ma teraz zależność środowiska wykonawczego od wtyczki Gradle do obsługi języka Kotlin (KGP) w wersji 2.2.10. Oznacza to, że nie musisz już deklarować wersji KGP, a jeśli używasz wersji KGP starszej niż 2.2.10, Gradle automatycznie uaktualni ją do wersji 2.2.10. Podobnie, jeśli używasz wersji KSP starszej niż 2.2.10–2.0.2, AGP zaktualizuje ją do wersji 2.2.10–2.0.2, aby była zgodna z wersją KGP.

Uaktualnianie do wyższej wersji KGP

Aby użyć wyższej wersji KGP lub KSP, dodaj ten kod do pliku najwyższego poziomu:

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:KGP_VERSION")

        // For KSP
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin:KSP_VERSION")
    }
}

Przechodzenie na niższą wersję KGP

Wersję KGP możesz obniżyć tylko wtedy, gdy zrezygnujesz z wbudowanego języka Kotlin. Dzieje się tak, ponieważ AGP 9.0 domyślnie włącza wbudowany język Kotlin, a wbudowany język Kotlin wymaga KGP w wersji 2.2.10 lub nowszej.

Aby użyć starszej wersji KGP lub KSP, zadeklaruj tę wersję w pliku kompilacji najwyższego poziomu za pomocą deklaracji ścisłej wersji:

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("KGP_VERSION") }
        }

        // For KSP
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin") {
            version { strictly("KSP_VERSION") }
        }
    }
}

Pamiętaj, że minimalna wersja KGP, do której możesz się cofnąć, to 2.0.0.

Obsługa środowiska IDE w przypadku plików testowych

AGP 9.0 zapewnia pełną obsługę środowiska IDE Android Studio w przypadku testów.

Wtyczka Fused Library

Wtyczka Fused Library (wersja zapoznawcza) umożliwia publikowanie wielu bibliotek jako pojedynczego pliku AAR biblioteki Androida. Ułatwi to użytkownikom korzystanie z opublikowanych artefaktów.

Więcej informacji o tym, jak zacząć, znajdziesz w artykule Publikowanie wielu bibliotek Androida jako jednej za pomocą biblioteki Fused.

Zmiany w działaniu

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

Wtyczka 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 wtyczki Androida do obsługi Gradle 8.13:

android {
  defaultConfig {
    testInstrumentationRunner = "..."
  }
}

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łaszanie zadania
• Obsługa pakietów APK podzielonych według gęstości ekranu
  AGP 9.0 usuwa obsługę tworzenia pakietów APK podzielonych według gęstości ekranu. Funkcja i powiązane z nią interfejsy API zostały usunięte. Aby podzielić pliki APK na podstawie gęstości ekranu za pomocą AGP 9.0 lub nowszego, użyj pakietów aplikacji.

Zmieniony DSL

Wtyczka Androida do obsługi Gradle w wersji 9.0 wprowadza 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 w unikaniu takich zmian w przyszłości. Oznacza to jednak również, że metody blokowania muszą zostać przeniesione z CommonExtension do ApplicationExtension, LibraryExtension, 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 metody 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 eksperymentalny, który nigdy nie został ustabilizowany PostProcessing.

• 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.

• DensitySplit, ponieważ ta funkcja nie jest już obsługiwana. Zamiast tego używaj pakietów aplikacji.

Usunięte interfejsy API

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

• AndroidComponentsExtension.finalizeDSl. Zastąpione przez:finalizeDsl

• Component.transformClassesWith. Zastąpione przez:Instrumentation.transformClassesWith

• Component.setAsmFramesComputationMode. Zastąpione przez: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żywaj 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 BaseExtension.registerTransformAPI, które były dostępne tylko po to, aby umożliwić kompilację z użyciem 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 z nich korzystają, 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 wersji 9.0 wtyczki AGP, które korzystają z tych właściwości.

Rozwiązane problemy

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

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

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

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

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

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

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

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

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