Плагин Android Gradle 9.0.1 (январь 2026 г.)

Плагин Android Gradle 9.0 – это основная версия, в которой изменены API и поведение.

Чтобы обновить плагин Android Gradle до версии 9.0.1, используйте ассистент обновления плагина Android Gradle. Помощник по обновлению AGP помогает сохранить существующее поведение при обновлении проекта, когда это необходимо. Таким образом, вы можете обновить проект до AGP 9.0, даже если вы не готовы принять все новые значения по умолчанию в AGP 9.0.

Чтобы упростить процесс обновления, можно использовать два навыка агента. Если вы не используете KMP, попробуйте навык обновления AGP 9 из репозитория навыков Android. Для приложений KMP попробуйте навык обновления AGP 9 от JetBrains. Подробнее о том, как использовать навыки в Android Studio…

Совместимость

Максимальный уровень API, поддерживаемый плагином Android Gradle 9.0, – 36.1. Другая информация о совместимости:

Классы DSL android теперь реализуют только новые общедоступные интерфейсы.

За последние несколько лет мы добавили новые интерфейсы для DSL и API, чтобы лучше контролировать, какие API являются общедоступными. В AGP версий 7.x и 8.x по-прежнему использовались старые типы DSL (например, BaseExtension), которые также реализовывали новые общедоступные интерфейсы, чтобы поддерживать совместимость по мере работы над интерфейсами.

В AGP 9.0 используются только новые интерфейсы DSL, а реализации изменены на новые типы, которые полностью скрыты. Также будет закрыт доступ к старому, неподдерживаемому варианту API.

Чтобы перейти на AGP 9.0, вам может потребоваться выполнить следующие действия:

• Убедитесь, что ваш проект совместим со встроенным языком Kotlin. Плагин org.jetbrains.kotlin.android несовместим с новым DSL.

• Переведите проекты KMP на плагин библиотеки Android Gradle для KMP. Использование плагина org.jetbrains.kotlin.multiplatform в том же подпроекте Gradle, что и плагины com.android.library и com.android.application, несовместимо с новым DSL.

• Обновите файлы сборки. Мы постарались сохранить DSL максимально похожим, но небольшие изменения все же есть.

• Обновите логику сборки, чтобы она ссылалась на новый DSL и API: Замените все ссылки на внутренний DSL интерфейсами общедоступного DSL. В большинстве случаев это будет замена один к одному. Замените все случаи использования applicationVariants и похожих API на новый androidComponents API. Это может быть сложнее, поскольку androidComponents API разработан так, чтобы быть более стабильным и обеспечивать совместимость плагинов в течение более длительного времени. Примеры можно найти в разделе Рецепты Gradle.

• Обновите сторонние плагины. Некоторые сторонние плагины могут по-прежнему зависеть от интерфейсов или API, которые больше не поддерживаются. Перейдите на версии этих плагинов, совместимые с AGP 9.0.

Переход на новые интерфейсы DSL предотвращает использование плагинами и скриптами сборки Gradle различных устаревших API, в том числе:

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

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

Если вы обновили AGP до версии 9.0 и видите следующее сообщение об ошибке, это означает, что в вашем проекте по-прежнему используются некоторые старые типы:

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

Если вы не можете использовать новые реализации из-за несовместимых сторонних плагинов, вы можете отказаться от них и вернуться к старым реализациям DSL и API вариантов. При этом новые интерфейсы также доступны, и вы можете обновить логику сборки до новой версии API. Чтобы отказаться от использования этой функции, добавьте в файл gradle.properties следующую строку:

android.newDsl=false

Если вы хотите перейти на новую версию постепенно, в AGP 9.4 можно отключить отдельные модули. Подробнее о том, как отказаться от использования модуля Variant API…

В AGP 9.0 предыдущие классы помечены как устаревшие. Это означает, что проекты, в которых не задан флаг newDsl, будут получать предупреждения об устаревании, в том числе в самом блоке android.

Вы также можете начать переход на новые API до обновления до AGP 9.0. Новые интерфейсы присутствуют во многих версиях AGP, поэтому вы можете использовать как новые, так и старые. В справочной документации по AGP API описана платформа API для каждой версии AGP, а также указано, когда был добавлен каждый класс, метод и поле.

Мы связываемся с авторами популярных плагинов, чтобы помочь им адаптировать и выпустить плагины, полностью совместимые с новыми режимами. Кроме того, мы продолжаем улучшать ассистент обновления AGP в Android Studio, чтобы помочь вам перейти на новые режимы.

Если вы обнаружите, что в новом DSL или Variant API отсутствуют какие-либо возможности или функции, как можно скорее сообщите об этой проблеме.

Встроенная поддержка Kotlin

В плагине Android Gradle 9.0 добавлена встроенная поддержка Kotlin, которая включена по умолчанию. Это означает, что вам больше не нужно применять плагин org.jetbrains.kotlin.android (или kotlin-android) в файлах сборки, чтобы компилировать исходные файлы Kotlin. Это упрощает интеграцию Kotlin с AGP, позволяет избежать использования устаревших API и в некоторых случаях повышает производительность.

Поэтому при обновлении проекта до AGP 9.0 вам также нужно будет перейти на встроенный Kotlin или отказаться от него.

Вы также можете отключить встроенную поддержку Kotlin для подпроектов Gradle, в которых нет источников Kotlin.

Зависимость от плагина Kotlin Gradle во время выполнения

Чтобы обеспечить встроенную поддержку Kotlin, плагин Android Gradle 9.0 теперь имеет зависимость времени выполнения от плагина Kotlin Gradle (KGP) 2.2.10. Это означает, что вам больше не нужно указывать версию KGP, а если вы используете версию KGP ниже 2.2.10, Gradle автоматически обновит ее до версии 2.2.10. Аналогично, если вы используете версию KSP ниже 2.2.10-2.0.2, AGP обновит ее до 2.2.10-2.0.2, чтобы она соответствовала версии KGP.

Как перейти на более новую версию KGP

Чтобы использовать более новую версию KGP или KSP, добавьте в файл сборки верхнего уровня следующие строки:

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

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

Как перейти на более раннюю версию KGP

Вы можете понизить версию KGP, только если отключили встроенную поддержку Kotlin. Это связано с тем, что AGP 9.0 по умолчанию включает встроенный Kotlin, а для встроенного Kotlin требуется KGP 2.2.10 или более поздней версии.

Чтобы использовать более раннюю версию KGP или KSP, укажите ее в файле сборки верхнего уровня, используя строгое объявление версии:

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

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

Обратите внимание, что минимальная версия KGP, до которой можно выполнить откат, – 2.0.0.

Поддержка тестовых наборов в IDE

В AGP 9.0 добавлена полная поддержка тестовых фикстур в IDE Android Studio.

Плагин Fused Library

Плагин Fused Library (предварительная версия) позволяет опубликовать несколько библиотек в виде одного файла AAR библиотеки Android. Это упростит использование опубликованных вами артефактов.

Информацию о том, как начать работу, можно найти в статье Как опубликовать несколько библиотек Android как одну с помощью Fused Library.

Изменения в поведении

В плагине Android Gradle 9.0 реализованы следующие новые функции:

В AGP 9.0 изменены значения по умолчанию для следующих свойств Gradle. При обновлении вы можете сохранить поведение AGP 8.13:

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

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

Удаленные функции

В плагине Android Gradle 9.0 удалены следующие функции:

• Поддержка встроенных приложений для Wear OS
  В AGP 9.0 удалена поддержка встроенных приложений для Wear OS, которая больше не поддерживается в Google Play. В частности, будут удалены конфигурации wearApp и DSL AndroidSourceSet.wearAppConfigurationName. Подробнее о том, как распространять приложения для Wear OS…
• androidDependencies и sourceSets report task
• Поддержка раздельных APK на основе плотности экрана
  В AGP 9.0 больше нельзя создавать раздельные APK на основе плотности экрана. Функция и связанные с ней API удалены. Чтобы разделить APK-файлы по плотности экрана с помощью AGP 9.0 или более поздней версии, используйте наборы App Bundle.

Измененный DSL

В плагине Android Gradle 9.0 произошли следующие критические изменения в DSL:

• Параметризация функции CommonExtension удалена.

  Само по себе это изменение на уровне источника не нарушает совместимость, но помогает избежать таких нарушений в будущем. Однако это также означает, что методы блокировки необходимо перенести из CommonExtension в ApplicationExtension, LibraryExtension, DynamicFeatureExtension и TestExtension.

  При обновлении проекта до AGP 9.0 выполните рефакторинг кода плагина Gradle, в котором используются эти параметры или методы блокировки. Например, в следующем плагине удален параметр type и не используются методы удаленного блока:

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

  Если плагин предназначен для работы с несколькими версиями AGP, прямое использование метода получения будет двоично совместимо с версиями AGP ниже 9.0.

Удаление DSL

В плагине Android Gradle 9.0 удалены:

• AndroidSourceSet.jni, поскольку он не работал.

• AndroidSourceSet.wearAppConfigurationName, поскольку поддержка встроенных приложений для Wear OS была удалена.

• BuildType.isRenderscriptDebuggable, поскольку он не работал.

• DependencyVariantSelection. Вместо него используется DependencySelection, который представлен как kotlin.android.localDependencySelection.

• Installation.installOptions(String). Теперь вместо него используется изменяемое свойство Installation.installOptions.

• Блок PostProcessing, который находится на экспериментальной стадии, но никогда не будет стабилизирован.

• ProductFlavor.setDimension, которое заменено свойством dimension

• LanguageSplitOptions, который использовался только для Google Play Instant, но эта функция больше не поддерживается.

• DensitySplit, поскольку эта функция больше не поддерживается. Вместо него рекомендуется использовать наборы приложений.

Удаленные API

В плагине Android Gradle 9.0 удалены:

• AndroidComponentsExtension.finalizeDSl. Вместо него используется атрибут finalizeDsl.

• Component.transformClassesWith. Вместо него используется атрибут Instrumentation.transformClassesWith.

• Component.setAsmFramesComputationMode. Вместо него используется атрибут Instrumentation.setAsmFramesComputationMode.

• ComponentBuilder.enabled. Вместо него используется ComponentBuilder.enable.

• DependenciesInfoBuilder.includedInApk. Вместо него используется includeInApk.

• DependenciesInfoBuilder.includedInBundle. Вместо него используется includeInBundle.

• GeneratesApk.targetSdkVersion. Вместо него используется targetSdk.

• Variant.minSdkVersion. Вместо него используется minSdk.

• Variant.maxSdkVersion. Вместо него используется maxSdk.

• Variant.targetSdkVersion. Вместо него используется targetSdk.

• Variant.unitTest, поскольку он не применялся к плагину com.android.test. Разметка unitTest доступна для подтипов VariantBuilder, которые расширяют HasUnitTest.

• VariantBuilder.targetSdk и targetSdkPreview, поскольку они не имели смысла в библиотеках. Вместо него необходимо использовать GeneratesApkBuilder.targetSdk или GeneratesApkBuilder.targetSdkPreview.

• VariantBuilder.enableUnitTest, поскольку он не применялся к плагину com.android.test. Разметка enableUnitTest доступна для подтипов VariantBuilder, которые расширяют HasUnitTestBuilder.

• VariantBuilder.unitTestEnabled удалено в пользу более единообразного названия enableUnitTest в подтипах VariantBuilder, расширяющих HasUnitTestBuilder.

• VariantOutput.enable. Вместо него используется enabled.

• Устаревшие и отключенные функции FeaturePlugin и FeatureExtension.

• Устаревшие и отключенные API BaseExtension.registerTransform, которые оставались только для того, чтобы разрешить компиляцию с использованием последней версии AGP при нацеливании на запуск в AGP 4.2 или более ранней версии.

Удалены свойства Gradle

Указанные ниже свойства Gradle изначально были добавлены для глобального отключения функций, которые были включены по умолчанию.

Эти функции отключены по умолчанию в AGP 8.0 и более ранних версиях. Включайте эти функции только в тех подпроектах, где они используются, чтобы сборка была более эффективной.

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

Принудительно применяемые свойства Gradle

AGP 9.0 выдает ошибку, если заданы следующие свойства Gradle:

Помощник по обновлению плагина Android Gradle не будет обновлять проекты до версии 9.0, если в них используются эти свойства.

Изменения в R8

В AGP 9.0.0 включены следующие изменения R8:

Новый вариант конфигурации -processkotlinnullchecks

Мы добавили новый параметр R8 -processkotlinnullchecks, позволяющий настроить R8 для обработки проверок на наличие нулевого значения в Kotlin. Этот параметр принимает обязательный аргумент, который должен быть одним из следующих трех значений: keep, remove_message и remove. Этот параметр обрабатывает следующие проверки на нулевое значение, добавленные компилятором Kotlin:

class kotlin.jvm.internal.Intrinsics {
  void checkNotNull(java.lang.Object);
  void checkNotNull(java.lang.Object, java.lang.String);
  void checkExpressionValueIsNotNull(
      java.lang.Object, java.lang.String);
  void checkNotNullExpressionValue(
      java.lang.Object, java.lang.String);
  void checkReturnedValueIsNotNull(
      java.lang.Object, java.lang.String);
  void checkReturnedValueIsNotNull(
      java.lang.Object, java.lang.String, java.lang.String);
  void checkFieldIsNotNull(java.lang.Object, java.lang.String);
  void checkFieldIsNotNull(
      java.lang.Object, java.lang.String, java.lang.String);
  void checkParameterIsNotNull(java.lang.Object, java.lang.String);
  void checkNotNullParameter(java.lang.Object, java.lang.String);
}

Значения параметра, упорядоченные от самого слабого до самого сильного, имеют следующее влияние:

• keep не меняет проверки.
• remove_message переписывает каждый вызов метода проверки на вызов getClass() для первого аргумента вызова (фактически сохраняя проверку на null, но без какого-либо сообщения).
• remove полностью удаляет проверки.

По умолчанию R8 использует remove_message. Любое значение -processkotlinnullchecks переопределит это правило. Если указано несколько значений, используется наиболее сильное.

Прекратить передачу информации о сохранении в дополнительные методы

Если правила сохранения соответствуют методам интерфейса, которые подвергаются десахаризации, R8 ранее внутренне передавал биты disallow optimization и disallow shrinking синтезированным сопутствующим методам.

Начиная с версии AGP 9.0, правила сохранения больше не применяются к дополнительным методам. Это согласуется с тем, что правила сохранения не применяются к другим полям, методам и классам, синтезированным компилятором.

Перенеся биты disallow optimization и disallow shrinking в дополнительные методы, мы ранее поддерживали следующий вариант использования:

1. Скомпилируйте библиотеку с методами интерфейса default/static/private в DEX с minSdk < 24 и правилами, которые сохраняют методы интерфейса.
2. Скомпилируйте приложение с библиотекой в classpath и -applymapping.
3. Объедините приложение и библиотеку.

Обратите внимание, что это работает только с -applymapping, поскольку бит disallow obfuscation не передается вспомогательным методам. Это означает, что вспомогательные классы, сгенерированные на шаге 1, будут иметь обфусцированные имена методов.

В дальнейшем этот вариант использования не будет поддерживаться для minSdk <0x0A>24. Чтобы обойти эту проблему, выполните следующие действия:

1. Десахаризация библиотеки с помощью методов интерфейса default/static/private в файлы классов с minSdk < 24.
2. Скомпилируйте десахаризованный артефакт с помощью R8 и правил, которые сохраняют методы интерфейса в сопутствующих классах.
3. Скомпилируйте приложение с библиотекой в пути к классам.
4. Объединить приложение и десахарированный артефакт.

Ещё одно побочное следствие этого изменения – невозможность сохранить атрибуты внутреннего класса и метода, содержащего анонимный или локальный класс, в методах-компаньонах интерфейса.

Изменить исходный файл по умолчанию на r8-map-id-<MAP_ID>

Это изменение реализовано в AGP версии 8.12.0 и более поздних.

Атрибут исходного файла, который по умолчанию передается для класса, меняется с SourceFile на r8-map-id-<MAP_ID>, когда требуется обратная трассировка (то есть когда включена обфускация или оптимизация).

Новый атрибут исходного файла позволяет извлекать идентификатор файла сопоставления, необходимого для восстановления исходного кода, из обфусцированной трассировки стека. Это позволяет автоматически восстанавливать исходный код трассировки стека в logcat.

Если используется настраиваемый атрибут файла источника (-renamesourcefileattribute), он по-прежнему имеет приоритет.

В режиме совместимости с ProGuard (когда gradle.properties содержит android.enableR8.fullMode=false) атрибут исходного файла r8-map-id-<MAP_ID> будет работать, только если атрибут SourceFile не сохранен. Если вы используете режим совместимости ProGuard и хотите, чтобы идентификатор файла сопоставления был включен в трассировку стека, удалите -keepattributes SourceFile или перейдите на полный режим R8.

Идентификатор карты, используемый в r8-map-id-<MAP_ID>, представляет собой полный хеш карты, а не префикс из семи символов, как раньше.

Включить использование сокращенных синтетических имен при десахаризации L8

Название синтетических классов, созданных D8, обычно содержит подстроку $$ExternalSynthetic, которая указывает на то, что класс был создан D8. Кроме того, название синтетического метода содержит информацию о его типе (например, Backport, Lambda). Это негативно влияет на размер файла DEX, поскольку названия классов занимают больше места в пуле строк.

AGP 9.0 настраивает L8 (десахаризацию основной библиотеки) таким образом, чтобы DEX-файл, содержащий все классы j$, использовал новый сокращенный формат названия класса для синтетических классов. Новое название класса содержит числовой идентификатор (например, $1).

Удалить поддержку -addconfigurationdebugging

В AGP 9.0 прекращена поддержка -addconfigurationdebugging. Теперь при использовании этого флага компилятор выдает предупреждение.

Удаление поддержки создания правил L8 из D8/R8

Это изменение касается только разработчиков, которые используют командную строку или API D8/R8 напрямую.

В R8 9.0 прекращена поддержка создания правил сохранения для L8 из D8 и R8. Вместо этого используйте TraceReferences.

В частности, удалены методы D8Command.builder.setDesugaredLibraryKeepRuleConsumer и R8Command.Builder.setDesugaredLibraryKeepRuleConsumer, а также поддержка --desugared-lib-pg-conf-output из параметров командной строки D8 и R8.

Устраненные проблемы

Плагин Android Gradle 9.0.0