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

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

Чтобы перейти на плагин Android Gradle версии 9.0.1, используйте помощник по обновлению плагина Android Gradle. Помощник по обновлению AGP позволяет сохранить существующее поведение при обновлении проекта, поэтому вы можете перейти на 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. Это может быть сложнее, поскольку API androidComponents разработан так, чтобы быть более стабильным и дольше сохранять совместимость плагинов. Примеры можно найти в рецептах 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, для которого требуется KGP 2.2.10 или более поздней версии.

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

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 добавлена полная поддержка тестовых фикстур в Android Studio IDE.

Плагин Fused Library

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

Подробнее о том, как опубликовать несколько библиотек 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
• Поддержка раздельных 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, так как эта функция больше не поддерживается. Вместо этого используйте наборы App Bundle.

Удаленные 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 не будет обновлять до AGP 9.0 проекты, в которых используются эти свойства.

Изменения R8

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

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

Мы добавили новый параметр R8 -processkotlinnullchecks для настройки R8, чтобы обрабатывать проверки Kotlin на null. Для этого параметра необходимо указать одно из трех значений: 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 ранее внутренне передавал биты запретить оптимизацию и запретить сжатие синтезированным сопутствующим методам.

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

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

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

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

В дальнейшем этот вариант использования больше не будет поддерживаться для minSdk < 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.

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

В 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