Плагин 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 или функция | Требуется замена или необходимо действие |
|---|---|
Прямой доступ к задачам:
|
Artifacts API. Вместо того чтобы получать задачу для изменения ее поведения, используйте variant.artifacts, чтобы добавлять, изменять или заменять фактические файлы (артефакты), передаваемые между задачами.
|
Немедленная регистрация источника:
|
Sources API. Подключите выходной каталог специальной задачи с помощью variant.sources.java.addGeneratedSourceDirectory(...).
|
Доступ к Classpath и конфигурации:
|
Instrumentation API. Чтобы изменить или проверить байт-код (самый распространенный вариант использования доступа к пути к классам), используйте variant.instrumentation.transformClassesWith(...) с AsmClassVisitorFactory.
|
Немедленное изменение свойства:
|
Экземпляры `MapProperty` с отложенной инициализацией: используйте variant.buildConfigFields.put(...) и variant.manifestPlaceholders.put(...).
|
Флаги отказа:
|
Прямой замены нет. Удалите эти флаги из gradle.properties. Использование современного DSL и встроенного Kotlin строго обязательно.
|
Расширения устаревшего Variant API:
|
Заменить на androidComponents.onVariants(). |
Фильтрация вариантов (variantFilter блок) |
Замените на androidComponents.beforeVariants(), используя селекторы вариантов.
|
Компоненты SDK и NDK:
|
Доступ к компонентам SDK с помощью androidComponents.sdkComponents.
|
Тестовые среды:
|
Перенесите регистрацию пользовательских тестовых устройств на устройства под управлением Gradle. |
Устаревшие API регистрации:
|
Удалено без прямой замены. |
| Transform API |
Замените преобразования на Artifacts API и AsmClassVisitorFactory.
|
Чтобы получить доступ ко всем заменяющим интерфейсам и классам DSL и Variant API (androidComponents {}), всегда используйте артефакт gradle-api при разработке пользовательских плагинов Gradle или логики сборки.
Этапы переноса
Чтобы переход на AGP 10.0 прошел без проблем, следуйте этим рекомендациям:
- Запустите AGP Upgrade Assistant. Прежде чем переходить на версию 10.0, запустите официальный инструмент AGP Upgrade Assistant в Android Studio (
Tools > AGP Upgrade Assistant). Он автоматизирует несколько распространенных переносов DSL и скриптов сборки и помогает сохранить существующие варианты поведения сборки. - Используйте навыки режима агента в Android Studio. Навыки обновления ИИ, например навыки обновления AGP, доступные в хранилище навыков Android, позволяют автоматизировать и упростить перенос сложной логики сборки и DSL в Android Studio.
- Сначала устраните предупреждения об устаревших функциях в AGP 9.x. Обновите проект до последней версии AGP 9.x и устраните все предупреждения об устаревших функциях. Если ваш проект работает с версией 9.x без предупреждений и не зависит от
android.newDsl=falseилиandroid.builtInKotlin=false, переход на версию 10.0 пройдет без проблем. - Проверьте сторонние плагины Gradle. Убедитесь, что они обновлены до версий, совместимых с AGP 10.0. Плагины, которые по-прежнему используют устаревшие типы расширений, будут вызывать ошибки сборки, например
ClassCastException: ... cannot be cast to class BaseExtension. - Используйте официальные рецепты переноса. Примеры переноса сложных реальных проектов и параллельные сравнения можно найти в официальном репозитории 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, сообщите нам об этом:
- Проверьте существующие записи. Сначала проверьте глобальную ошибку отслеживания AGP 10.0 Variant API, чтобы узнать, известна ли уже проблема, блокирующая переход, и поставьте ей +1.
- Сообщите об отсутствующих 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, расположенные в других артефактах, по-прежнему доступны во время компиляции файлов сборки и плагинов, но мы не рекомендуем их использовать, поскольку они могут в любой момент измениться.