График миграции DSL/API плагина Android Gradle

Android Gradle Plugin (AGP) — это поддерживаемая система сборки для приложений Android, которая включает в себя поддержку компиляции множества различных типов исходных файлов и их объединения в приложение, которое можно запускать на физическом устройстве Android или в эмуляторе.

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

Более подробный список устаревших или удаленных функций API AGP см. в разделе « Обновления API AGP» .

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

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

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

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

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

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

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

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

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

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

Что демонтируется и заменяется

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

Удалён API или функция. Необходима замена или действия.
Прямой доступ к задаче:
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
 API для работы с артефактами: вместо получения данных о задаче для изменения ее поведения используйте variant.artifacts для добавления, изменения или замены фактических файлов (артефактов), передаваемых между задачами.
Активная регистрация источника:
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
 API источников: Укажите выходной каталог вашей пользовательской задачи с помощью variant.sources.java.addGeneratedSourceDirectory(...) .
Доступ к Classpath/configuration:
  • getCompileConfiguration()
  • getCompileClasspath()
 API инструментирования: Для изменения или анализа байт-кода (наиболее распространенный вариант использования доступа к classpath) используйте variant.instrumentation.transformClassesWith(...) с помощью AsmClassVisitorFactory .
Стремительная мутация свойств:
  • buildConfigField()
  • resValue()
 Ленивые экземпляры `MapProperty`: используйте variant.buildConfigFields.put(...) и variant.manifestPlaceholders.put(...) .
Флаги отказа от участия:
  • android.newDsl
  • android.builtInKotlin
 Прямая замена отсутствует. Удалите эти флаги из gradle.properties ; здесь строго соблюдаются требования современного DSL и встроенного Kotlin.
Расширения 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
 Удалено без прямой замены.
API преобразования Замените преобразования на API артефактов и AsmClassVisitorFactory .

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

Этапы миграции

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

  1. Запустите помощник обновления AGP: Перед прямым обновлением до версии 10.0 запустите официальный помощник обновления AGP в 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 {} :

Ранее: устаревший вариант 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
        }
    }
}

После: Современный вариант 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 отключены все параметры отказа от использования AGP и установлены следующие флаги строгого поведения:

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

Процесс обратной связи и сообщения об ошибках

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

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

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

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

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

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

Новые API-интерфейсы для работы с различными вариантами кода являются стабильными, старые API-интерфейсы устарели.

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

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

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

Доступны и частные внутренние занятия по программе AGP.

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