Последняя строка `BUILD FAILED` почти бесполезна. В React Native одна ошибка конфигурации создаёт десятки вторичных: не найден plugin, не запустился Codegen, не скомпилировался Kotlin, пропали generated sources. Ищите первую задачу, которая упала, и первый блок `Caused by`.

Перед правкой зафиксируйте toolchain. React Native Gradle Plugin устанавливается вместе с `react-native`, настраивает зависимости, repositories, bundling, Hermes и Codegen. Если `node_modules`, settings plugin и версия RN не образуют один комплект, обновление AGP в одиночку не поможет.

Снимок окружения воспроизводит половину ошибок

node --version
npx react-native info
cd android
./gradlew --version
./gradlew :app:assembleDebug --stacktrace --warning-mode all

# Windows PowerShell/cmd:
gradlew.bat --version
gradlew.bat :app:assembleDebug --stacktrace --warning-mode all

`./gradlew` использует wrapper проекта; системный `gradle` может быть другой версии. В выводе `--version` смотрите Gradle и JVM. Android указывает: JDK, запускающий Gradle, должен соответствовать требованиям AGP; например, ветки AGP 8.x требуют JDK 17. Точное соответствие берут из release notes используемой версии, а не из случайной статьи.

Фаза падения указывает владельца настройки

Фаза/задачаТипичная причинаПервый файл для проверки
settings/pluginManagementне найден RNGP/includeBuildandroid/settings.gradle
configurationAGP/Gradle/JDK несовместимыwrapper + top-level build.gradle
dependency resolutionrepository/версия native moduledependencyInsight/lockfile
generateCodegenArtifactsschema или пакет не поддержанpackage.json и library config
compileKotlin/JavaAPI/target/toolchain mismatchпервая исходная ошибка
merge/packagingmanifest/resource/duplicate classmerged manifest/dependency graph

Community Template — контроль, а не рецепт обновить всё

Создайте временный пустой проект той же версии React Native или откройте соответствующий Community Template. Сравните `settings.gradle`, верхний `build.gradle`, `gradle-wrapper.properties`, plugin application и блок `react`. Текущий RN использует settings plugin для autolinking и отдельный React Native Gradle Plugin; старые фрагменты из прошлых поколений могут конфликтовать.

  • Не копируйте номера AGP и Gradle из latest template в старую RN-ветку.
  • Не указывайте вручную версию react-android, если ею должен управлять RNGP.
  • Проверьте относительный путь к node_modules в monorepo.
  • Сверьте package manager lockfile и реально установленную версию @react-native/gradle-plugin.
  • Сохраните diff конфигурации перед автоматическим upgrade.

Локальная сборка и CI обязаны использовать одну матрицу

Android Studio может запускать Gradle bundled JDK, терминал — JAVA_HOME, а CI — JDK из container image. Поэтому «на моём компьютере работает» проверяют сравнением `./gradlew --version`. Версии Node, package manager и Android SDK/NDK также фиксируют в build log. Секреты подписи не печатают.

РазличиеПризнакИсправление
JDKunsupported class/AGP requires Javaединый Gradle JDK/toolchain
Node/node_modulesplugin path/codegen missinglockfile + deterministic install
SDK/NDKplatform/side-by-side NDK not foundявная версия и CI install
architecture flagsCMake/ABI failureсогласовать reactNativeArchitectures
case-sensitive FSлокально есть, Linux CI нетисправить регистр путей/import

Clean полезен только после объяснения причины

`clean` удаляет outputs, но не исправляет несовместимость версий. Удаление всех Gradle caches заставляет заново скачивать зависимости и маскирует intermittent repository failure. Сначала воспроизведите ошибку, сохраните dependency graph и stacktrace; затем удаляйте конкретный build directory или повреждённый module cache с возможностью повторить исходный тест.

Минимальный upgrade идёт по одному измерению

  1. Зафиксировать чистую ветку, lockfile и текущую ошибку Debug/Release.
  2. Сверить RN-конфигурацию с template той же версии.
  3. Привести JDK к требованиям текущего AGP и повторить wrapper build.
  4. Исправить первую фазу, не меняя одновременно все native modules.
  5. Запустить assembleDebug и release bundle без ключей публикации.
  6. Повторить в CI с теми же версиями Node/JDK/SDK.
  7. Только затем обновлять следующий компонент матрицы и сохранять diff.

Для диагностики нужны package.json/lockfile, четыре Gradle-файла без signing secrets, `npx react-native info`, `gradlew --version` и первый stacktrace block. Не присылайте keystore, пароли или полный env. Исправление завершено, когда wrapper воспроизводимо собирает Debug и Release локально и на чистом CI runner.

Проверенные источники