Как безопасно обновить Gradle, AGP и зависимости в Android‑проекте

Коротко: обновляйте в порядке — Gradle Wrapper → Android Gradle Plugin → Kotlin/плагины → библиотеки; после каждого шага запускайте сборку и фиксируйте ошибки. Ниже — компактный пошаговый план, команды и готовые рецепты устранения типичных ошибок.

Перед стартом — подготовка и общая последовательность

• Создайте ветку/тэг в git и закоммитьте текущее состояние (git tag/branch).
• Порядок обновлений: 1) Gradle Wrapper, 2) AGP (classpath или version catalog), 3) Kotlin и плагины, 4) зависимости. Между шагами выполняйте ./gradlew clean assembleDebug и исправляйте ошибки.

Полезные команды:

./gradlew wrapper --gradle-version 8.13 --distribution-type all
./gradlew --version
./gradlew clean assembleDebug --stacktrace --info

Пошаговый алгоритм обновления

1. Обновите wrapper:
   • Выполните команду wrapper или правьте gradle/wrapper/gradle-wrapper.properties.
   • Закоммитьте gradlew, gradlew.bat и содержимое gradle/wrapper/.
2. Обновите AGP:
   • В корневом build.gradle (или версиях в settings.gradle.kts/version catalog) задайте нужную com.android.tools.build:gradle.
   • Синхронизируйте проект, собирайте и фиксируйте ошибки.
3. Обновите Kotlin/плагины:
   • Подберите совместимую версию Kotlin с AGP.
   • Проверьте необходимость плагина org.jetbrains.kotlin.android при AGP 9+.
4. Обновите библиотеки:
   • Переведите версии в Version Catalog (gradle/libs.versions.toml) для централизованного управления.
   • Используйте ben‑manes плагин для аудита:

plugins { id "com.github.ben-manes.versions" version "0.47.0" }
./gradlew dependencyUpdates

Типичные ошибки сборки и готовые решения

• "Minimum supported Gradle version is X": обновите wrapper и запускайте ./gradlew из репозитория (CI должен использовать wrapper).
• "Could not find com.android.tools.build:gradle": добавьте репозитории google() и mavenCentral(), убедитесь, что нет оффлайн-режима.
• Ошибки namespace/compileSdk: добавьте в модуле

android {
  namespace "com.example.app"
  compileSdk 34
}

• Duplicate class: посмотрите дерево зависимостей (./gradlew :app:dependencies --configuration debugRuntimeClasspath), исключите транзитивы:

implementation('com.some:lib:1.2.3') { exclude group: 'com.conflict', module: 'conflicting-module' }

• KAPT/annotation processor: обновите версии процессоров, включите correctErrorTypes, или мигрируйте на KSP.
• Dex limit / multidex: включите multiDexEnabled и добавьте androidx.multidex, либо уменьшите зависимости.

Инструменты и практики поддержки

• Version Catalogs (libs.versions.toml) — централизованное управление версиями.
• Ben‑manes/versions — регулярная проверка устаревших артефактов.
• BOM для согласованных семейств библиотек.
• Dependency constraints/force для выравнивания транзитивных версий.

Частые ошибки

• CI использует системный gradle вместо wrapper — исправьте скрипты CI.
• Несоответствие JDK (на CI требуется JDK 17+ для новых Gradle/AGP).
• Старые кеши в CI/локально — решается очисткой кэша и ./gradlew --stop.

FAQ

• Как быстро понять, какая версия Gradle нужна для AGP?
  Проверьте релиз‑ноты AGP: там указаны минимальная поддерживаемая версия Gradle и требуемая JDK.
• Можно ли автоматизировать обновление всех зависимостей?
  Можно, но не рекомендуется без ручной проверки: автоматические апдейты часто ломают API.
• Что делать, если после апдейта падают annotation processors?
  Обновите версии процессоров, включите kapt.correctErrorTypes = true или мигрируйте на KSP.

Чеклист перед релизом после апдейта:

• Собраны debug/release, пройдены тесты, CI билд на чистой машине, обновлены инструкции окружения, закоммичены wrapper/versions.toml.

Если хотите, пришлите build.gradle(ов) и gradle-wrapper.properties — подготовлю пошаговый план обновления и пример libs.versions.toml под ваш проект.