Сроки перехода на DSL/API плагина Android Gradle

Плагин Android Gradle (AGP) – это поддерживаемая система сборки для приложений Android. Она позволяет компилировать различные типы источников и связывать их в приложение, которое можно запустить на физическом устройстве Android или в эмуляторе.

В следующем разделе описывается запланированная эволюция DSL и API AGP. По мере появления новых API в стабильных выпусках старые API будут помечаться как устаревшие. В следующем стабильном выпуске эти API станут недоступны. В следующих разделах представлена информация о предстоящих изменениях в каждом основном выпуске AGP.

Подробный журнал прекращения поддержки и удаления API плагина Android для Gradle можно найти в обновлениях API плагина Android для Gradle.

AGP 10.0 (конец 2026 г.)

Изменения и модернизация API плагина Android Gradle 10.0

В AGP 10.0 завершен переход на полностью ленивую модель сборки, совместимую с кешем конфигурации. Этот выпуск – кульминация многолетней работы по замене устаревших API, не поддерживающих отложенную загрузку, на более безопасную и производительную архитектуру.

Почему используется модель ленивой сборки?

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

Переход на полностью ленивую модель сборки с использованием ленивых поставщиков (Provider<T>) и современного Variant API (androidComponents {}) позволяет вычислять свойства и связи задач по запросу, только когда это необходимо для активного графа выполнения сборки.

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

Основное различие в архитектуре

Устаревший API BaseVariant (applicationVariants.all {}) был ориентирован на задачи. Он предоставлял разработчикам прямой доступ к задачам Gradle и внутренним конфигурациям на этапе настройки, что по своей сути нарушает современные функции производительности Gradle.

Новый Variant API (androidComponents {}) ориентирован на артефакты и использует отложенную инициализацию. Он активно использует Property API Gradle и полностью удаляет все ссылки на Task и TaskProvider, требуя от вас взаимодействия с входными и выходными данными (Variant.artifacts), а не с самими базовыми задачами.

Что будет удалено и заменено

Все интерфейсы и классы, которые использовались в устаревшем DSL и старом Variant API, удалены. Чтобы подготовить скрипты сборки и пользовательские плагины, откажитесь от использования следующих API и флагов, поддержка которых прекращена:

Удаленный API или функция Требуется замена или необходимо действие
Прямой доступ к задачам:
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
Artifacts API. Вместо того чтобы получать задачу для изменения ее поведения, используйте variant.artifacts, чтобы добавлять, изменять или заменять фактические файлы (артефакты), передаваемые между задачами.
Немедленная регистрация источника:
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
Sources API. Подключите выходной каталог специальной задачи с помощью variant.sources.java.addGeneratedSourceDirectory(...).
Доступ к Classpath и конфигурации:
  • getCompileConfiguration()
  • getCompileClasspath()
Instrumentation API. Чтобы изменить или проверить байт-код (самый распространенный вариант использования доступа к пути к классам), используйте variant.instrumentation.transformClassesWith(...) с AsmClassVisitorFactory.
Немедленное изменение свойства:
  • buildConfigField()
  • resValue()
Экземпляры `MapProperty` с отложенной инициализацией: используйте variant.buildConfigFields.put(...) и variant.manifestPlaceholders.put(...).
Флаги отказа:
  • android.newDsl
  • android.builtInKotlin
Прямой замены нет. Удалите эти флаги из gradle.properties. Использование современного DSL и встроенного Kotlin строго обязательно.
Расширения устаревшего Variant API:
  • applicationVariants
  • libraryVariants
  • testVariants
  • unitTestVariants
Заменить на androidComponents.onVariants().
Фильтрация вариантов (variantFilter блок) Замените на androidComponents.beforeVariants(), используя селекторы вариантов.
Компоненты SDK и NDK:
  • sdkDirectory
  • ndkDirectory
  • bootClasspath
  • adbExecutable
Доступ к компонентам SDK с помощью androidComponents.sdkComponents.
Тестовые среды:
  • deviceProvider
  • testServer
Перенесите регистрацию пользовательских тестовых устройств на устройства под управлением Gradle.
Устаревшие API регистрации:
  • registerArtifactType
  • registerBuildTypeSourceProvider
  • registerProductFlavorSourceProvider
  • registerJavaArtifact
  • registerMultiFlavorSourceProvider
  • wrapJavaSourceSet
Удалено без прямой замены.
Transform API Замените преобразования на Artifacts API и AsmClassVisitorFactory.

Чтобы получить доступ ко всем заменяющим интерфейсам и классам DSL и Variant API (androidComponents {}), всегда используйте артефакт gradle-api при разработке пользовательских плагинов Gradle или логики сборки.

Этапы переноса

Чтобы переход на AGP 10.0 прошел без проблем, следуйте этим рекомендациям:

  1. Запустите AGP Upgrade Assistant. Прежде чем переходить на версию 10.0, запустите официальный инструмент AGP Upgrade Assistant в Android Studio (Tools > AGP Upgrade Assistant). Он автоматизирует несколько распространенных переносов DSL и скриптов сборки и помогает сохранить существующие варианты поведения сборки.
  2. Используйте навыки режима агента в Android Studio. Навыки обновления ИИ, например навыки обновления AGP, доступные в хранилище навыков Android, позволяют автоматизировать и упростить перенос сложной логики сборки и DSL в Android Studio.
  3. Сначала устраните предупреждения об устаревших функциях в AGP 9.x. Обновите проект до последней версии AGP 9.x и устраните все предупреждения об устаревших функциях. Если ваш проект работает с версией 9.x без предупреждений и не зависит от android.newDsl=false или android.builtInKotlin=false, переход на версию 10.0 пройдет без проблем.
  4. Проверьте сторонние плагины Gradle. Убедитесь, что они обновлены до версий, совместимых с AGP 10.0. Плагины, которые по-прежнему используют устаревшие типы расширений, будут вызывать ошибки сборки, например ClassCastException: ... cannot be cast to class BaseExtension.
  5. Используйте официальные рецепты переноса. Примеры переноса сложных реальных проектов и параллельные сравнения можно найти в официальном репозитории gradle-recipes на GitHub.

Ниже показано, как перейти от немедленного запроса устаревших вариантов к отложенной настройке вариантов с помощью androidComponents {}.

До: устаревший Variant API (удален в AGP 10.0)

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

После: современный Variant API (androidComponents {})

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

Как протестировать поведение AGP 10.0 в AGP 9.x

Не нужно ждать выпуска AGP 10.0, чтобы начать тестирование поведения сборки и проверку совместимости. При использовании любого выпуска AGP 9.x вы можете явно принудительно применить поведение AGP 10.0, убедившись, что ваш файл gradle.properties отключает все отказы и устанавливает следующие строгие флаги поведения:

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

Принудительно применяя android.newDsl=true и android.builtInKotlin=true, вы можете убедиться, что ваша собственная логика сборки и сторонние плагины полностью совместимы со строгими требованиями к API в AGP 10.0.

Выборочный отказ от переноса подпроектов

Если вы хотите включить android.newDsl=true глобально во всем проекте, чтобы протестировать современные функции, но вам нужно больше времени для переноса определенных подпроектов, вы можете выборочно отключить отдельные модули, начиная с AGP 9.4.0-alpha04. Добавьте android.newDsl.optOut в gradle.properties, указав пути к проекту:

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

Выборочное отключение встроенного Kotlin для отдельных модулей

Если вы хотите включить встроенный Kotlin глобально для всего проекта (android.builtInKotlin=true), но вам нужно больше времени, чтобы перенести определенные подпроекты с kotlin-android (или для модулей без кода Kotlin), настройте эти модули на уровне DSL, а не на уровне проекта. Задайте enableKotlin = false в файле сборки модуля:

android {
    enableKotlin = false
}

Как отправить отзыв или отчет об ошибке

Мы хотим убедиться, что новый Variant API поддерживает все необходимые вам сценарии использования. Если при переходе со старых API вы столкнетесь с проблемой, которую не удается решить с помощью нового Variant API, сообщите нам об этом:

  1. Проверьте существующие записи. Сначала проверьте глобальную ошибку отслеживания AGP 10.0 Variant API, чтобы узнать, известна ли уже проблема, блокирующая переход, и поставьте ей +1.
  2. Сообщите об отсутствующих API. Если у вас уникальный сценарий использования, отправьте запрос на добавление функции, используя специальный шаблон AGP 10.0. Мы изучим проблему и постараемся помочь.

(Предварительно) Доступ к частным внутренним классам AGP удален

Зависимость от артефакта gradle теперь скрывает все внутренние классы и предоставляет доступ к компиляции только для интерфейсов и классов, доступных в артефакте gradle-api. Это влияет на компиляцию плагина.

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

AGP 9.0 (январь 2026 г.)

Новые API вариантов стабильны, старые API больше не поддерживаются

Variant API, которые находились в инкубаторе в версиях 4.1 и 4.2, теперь стабильны и находятся в артефакте gradle-api. Прежние интерфейсы и классы, которые использовались в старом Variant API, теперь считаются устаревшими и требуют явного согласия на использование.

Новые интерфейсы DSL стабильны, старые устарели

Интерфейсы DSL, которые находились в инкубаторе в версиях 4.1, 4.2 и 7.0, теперь стабильны и находятся в артефакте gradle-api. Прежние интерфейсы и классы, используемые в DSL, теперь не поддерживаются и требуют явного согласия на использование.

Частные внутренние классы AGP по-прежнему доступны

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