Пошаговое руководство по безопасному обновлению

Коротко: зафиксируйте текущее состояние (коммит + тег), обновите Gradle wrapper по версии, синхронизируйте AGP в проекте, очистите кэши и постепенно тестируйте на эмуляторах/CI — так риск поломки минимален.

Подготовка перед обновлением

  1. Сделайте коммит и тег в Git:
    • git add . && git commit -m "pre-update-2026"
    • git tag pre-update-2026
  2. Сделайте бэкап локального .gradle (или просто сохраните папку).
  3. Очистите кэш и соберите текущую версию для сравнения:
    • ./gradlew clean assembleDebug
  4. Проверьте совместимость AGP, Gradle и Kotlin: сопоставьте требуемые версии AGP → Gradle → Kotlin (Kotlin 2.x обычно требует AGP 8.6+).
  5. Подготовьте CI/feature-ветку для тестового прогона — никогда не обновляйте сразу в main без проверки.

Если у вас старая версия Android Studio (ниже 2023.1), скачивайте новую IDE дистрибутивом, а не через встроенный апдейтер — некоторые плагины и настройки могут сломаться.

Обновление Android Studio

  • Установите свежую стабильную сборку IDE. При установке выберите сохранение настроек.
  • Откройте SDK Manager и обновите:
    • Android SDK Tools и Build Tools до рекомендованных версий;
    • нужные платформы API (рекомендуется тестировать на API 34+).
  • Перезапустите Studio и импортируйте проект — IDE предложит синхронизацию или обновление AGP.

Обновление AGP и Gradle wrapper

  1. Обновите gradle wrapper:
    • ./gradlew wrapper --gradle-version=8.7
    • проверьте gradle/wrapper/gradle-wrapper.properties -> distributionUrl.
  2. В корневом build.gradle (или settings.gradle.kts) задайте AGP:
    • plugins { id "com.android.application" version "8.7.0" apply false }
  3. Выполните первичную сборку:
    • ./gradlew clean build --no-daemon
  4. Если сборка падает — читайте логи по ключевым словам: "Kotlin compatibility", "Compose compiler", "NDK", "missing dependency".

Тестируйте каждое изменение отдельно: сначала wrapper, затем AGP, затем Kotlin/Compose. Это упрощает локализацию ошибки.

Сравнение ключевых версий AGP

AGPТребуемый GradleЧто важно
8.5.x8.6+стабильность для старых проектов
8.6.x8.6+официальная поддержка Kotlin 2.0
8.7.x8.7улучшения кэширования и совместимость с API 35

Решение типичных проблем

  • Gradle sync failed:
    • File > Sync Project with Gradle Files; увеличьте память в gradle.properties: org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m
  • Kotlin/Compose compiler errors:
    • Обновите версию компилятора Compose и Kotlin в модулях согласно таблице совместимости.
  • NDK/LLDB ошибки:
    • Установите соответствующую версию NDK через SDK Manager и укажите ndkVersion в модуле.
  • Плагины третьих сторон:
    • Проверьте совместимость плагинов; временно отключите те, что падают, или замените на обновлённые аналоги.

Откат (если что-то пошло не так)

  1. Вернитесь к тегу:
    • git checkout pre-update-2026
  2. Верните старый wrapper (если изменён):
    • восстановите gradle-wrapper.properties из бэкапа
  3. Очистите кэши .gradle и перезапустите сборку:
    • rm -rf ~/.gradle/caches && ./gradlew clean assembleDebug

Если у вас enterprise-проект — рассмотрите интеграцию Gradle Enterprise/Remote Build Cache до обновления: это ускорит отладку и повторные сборки.

Проверка после обновления

  • Соберите релизную сборку: ./gradlew assembleRelease
  • Прогоны юнит/инструментальных тестов и интеграционные тесты в CI.
  • Проверка UI (особенно для Compose): запустите эмуляторы с API 34+ и реальные устройства при возможности.
  • Сравните метрики сборки (время, потребление памяти) и поведение приложения.

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

  • Несовместимость Kotlin и AGP — обновляйте обе части согласно совместимости.
  • Забытый обновлённый buildToolsVersion или targetSdk — проверьте манифесты и module-level gradle.
  • Плагины, не поддерживающие новую AGP — отключите/замените.

FAQ

  • Нужно ли обновлять сразу все модули? Лучше последовательно: wrapper → AGP → модули/плагины.
  • Сколько времени займёт обновление? Обычно 30–60 минут для простого проекта, для монорепозитория — больше.
  • Что делать при ошибках в CI? Прогоните локально с --stacktrace, --info и проверьте те же JDK/Gradle-версии, что в CI.

Контрольный чеклист:

  • [ ] Коммит + тег pre-update
  • [ ] Бэкап .gradle
  • [ ] Обновлённый wrapper
  • [ ] Обновлённый AGP в корне
  • [ ] Прогоны локально и в CI
  • [ ] Тесты UI на эмуляторах/реалах

Удачного обновления — постепенный и тестируемый подход спасёт проект от неожиданных регрессий.