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

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

Для обновления до плагина Android Gradle версии 9.0.0 используйте помощник обновления плагина Android Gradle .

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

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

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

В классах android DSL теперь реализованы только новые публичные интерфейсы.

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

AGP 9.0 использует исключительно наши новые DSL-интерфейсы, а в реализациях используются новые, полностью скрытые типы. Это также исключает доступ к старому, устаревшему API вариантов.

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

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

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

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

• Обновите свою пользовательскую логику сборки, чтобы она ссылалась на новый DSL и API: замените все ссылки на внутренний DSL на публичные интерфейсы DSL. В большинстве случаев это будет замена один к одному. Замените любое использование applicationVariants и аналогичных API на новый API androidComponents . Это может быть сложнее, поскольку 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

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

В ходе альфа-тестирования версии 9.0 мы обращаемся к авторам плагинов с просьбой помочь им адаптировать и выпустить плагины, полностью совместимые с новыми режимами, а также усовершенствуем помощник по обновлению AGP в Android Studio, чтобы он помог вам выполнить миграцию.

Если вы обнаружите, что в новом DSL или 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 автоматически обновит вашу версию KGP до 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.devtoolsksp:symbol-processing-gradle-plugin:KSP_VERSION")
    }
}

Понизьте версию KGP до более старой.

Понижение версии KGP возможно только в том случае, если вы отказались от встроенного Kotlin . Это связано с тем, что AGP 9.0 по умолчанию включает встроенный 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.devtoolsksp:symbol-processing-gradle-plugin") {
            version { strictly("KSP_VERSION") }
        }
    }
}

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

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

AGP 9.0 обеспечивает полную поддержку тестовых наборов в среде разработки Android Studio.

Плагин объединенной библиотеки

Плагин Fused Library (предварительная версия) позволяет публиковать несколько библиотек в виде единого Android Library 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 удалена следующая функциональность:

• Поддержка приложений Embedded Wear OS
  В AGP 9.0 прекращена поддержка встраивания приложений Wear OS, которая больше не поддерживается в Play Store. Это включает в себя удаление конфигураций wearApp и DSL AndroidSourceSet.wearAppConfigurationName . Инструкции по публикации приложения в Wear OS см. в разделе «Распространение в Wear OS».
• задача отчета androidDependencies и sourceSets Android
• Поддержка разделения по плотности APK
  В AGP 9.0 удалена поддержка создания разделенных APK-файлов на основе плотности экрана. Функциональность и связанные с ней API были удалены. Для разделения APK-файлов на основе плотности экрана с использованием AGP 9.0 или более поздних версий используйте пакеты приложений .

Изменен DSL

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

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

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

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

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

Удалённые 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
  }
}

Объекты с принудительной регулировкой уровня грунта

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

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

Изменения в R8

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

Новая опция конфигурации -processkotlinnullchecks

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

Благодаря переносу функций запрета оптимизации и запрета уменьшения битов в сопутствующие методы, ранее поддерживался следующий вариант использования:

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

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

В дальнейшем этот вариант использования больше не поддерживается для minSdk < 24. В качестве обходного пути можно выполнить следующие действия:

1. Десахаризация библиотеки с методами интерфейса default / static / private методами в файлах классов с minSdk < 24.
2. Скомпилируйте десахаризованный артефакт, используя R8 и правила, которые сохраняют методы интерфейса в сопутствующих классах.
3. Скомпилируйте приложение, добавив библиотеку в classpath.
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> используется полный хеш карты, а не 7-символьный префикс хеша карты, который использовался ранее.

Разрешить использование сокращенных синтетических названий при десахарировании 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 plugin 9.0.0-rc03

Android Gradle plugin 9.0.0-rc02

Android Gradle plugin 9.0.0-rc01

Android Gradle plugin 9.0.0-beta05

Android Gradle plugin 9.0.0-beta04

Android Gradle plugin 9.0.0-beta03

Android Gradle plugin 9.0.0-beta02

Android Gradle plugin 9.0.0-beta01

Android Gradle plugin 9.0.0-alpha14

Android Gradle plugin 9.0.0-alpha13

Android Gradle plugin 9.0.0-alpha12

Android Gradle plugin 9.0.0-alpha11

Android Gradle plugin 9.0.0-alpha10

Android Gradle plugin 9.0.0-alpha09

Android Gradle plugin 9.0.0-alpha08

Android Gradle plugin 9.0.0-alpha07

Android Gradle plugin 9.0.0-alpha06

Android Gradle plugin 9.0.0-alpha05

Android Gradle plugin 9.0.0-alpha04

Android Gradle plugin 9.0.0-alpha03

Android Gradle plugin 9.0.0-alpha02

Android Gradle plugin 9.0.0-alpha01

Android Gradle plugin 9.0.0