Ошибка вида «Gradle sync failed» при первом запуске проекта чаще всего означает, что нужная версия Gradle не скачана, а не то, что система сборки не установлена вообще. Разобраться в этом важно до того, как скачивать что-то дополнительно: в большинстве случаев Android Studio уже содержит всё необходимое, а Gradle подтягивается автоматически при открытии проекта.
Тем не менее ситуации бывают разные: иногда требуется вручную указать конкретную версию, иногда — установить Gradle отдельно для работы из командной строки, а иногда — просто исправить конфликт версий. В этом материале разберём все сценарии: от автоматической установки до ручной настройки и решения типичных проблем.
Что такое Gradle и зачем он в Android Studio
Gradle — это система автоматической сборки, которая компилирует код, управляет зависимостями и формирует готовый APK- или AAB-файл. Android Studio использует её как основной инструмент сборки, поэтому без корректно работающего Gradle проект просто не соберётся.
Важно понимать разницу между тремя сущностями: Gradle (сама система сборки), Android Gradle Plugin (плагин, связывающий Gradle с Android SDK) и Gradle Wrapper (обёртка, которая автоматически скачивает нужную версию Gradle для конкретного проекта). Именно Wrapper избавляет от необходимости устанавливать Gradle вручную в большинстве случаев.
Автоматическая установка через Gradle Wrapper
Стандартный сценарий выглядит так: вы открываете проект, и Android Studio запускает синхронизацию. В ходе неё Wrapper проверяет файл gradle-wrapper.properties в папке gradle/wrapper вашего проекта и скачивает указанную там версию Gradle, если её нет в локальном кеше.
Чтобы процесс прошёл успешно, проверьте следующее:
- 🌐 Стабильное интернет-соединение — дистрибутив Gradle скачивается из сети при первой синхронизации.
- 💾 Свободное место на диске — каждая версия Gradle занимает заметный объём в кеше пользователя.
- 📁 Отсутствие кириллицы и пробелов в пути к проекту и к папке пользователя — это частая причина сбоев.
- 🔓 Разрешения антивируса и брандмауэра для Android Studio, если скачивание блокируется.
Если синхронизация зависла или завершилась ошибкой, сначала посмотрите текст сообщения в нижней панели Build. Там обычно указано, какая именно версия не смогла загрузиться и по какой причине.
Ручная установка Gradle на компьютер
Отдельная установка нужна, если вы планируете собирать проекты из командной строки, настраивать CI-сервер или использовать Gradle вне Android Studio. Порядок действий в этом случае такой:
- Скачайте дистрибутив Gradle с официального сайта проекта. Выбирайте пакет binary-only, если исходный код вам не нужен.
- Распакуйте архив в удобную папку, например
C:\Gradleна Windows или/opt/gradleна Linux. - Добавьте путь к подпапке
binв системную переменную окруженияPATH. - Проверьте установку командой в терминале:
gradle -vЕсли команда выводит информацию о версии — установка прошла успешно. Если система сообщает, что команда не найдена, перепроверьте переменную PATH и перезапустите терминал после её изменения.
⚠️ Внимание: для работы Gradle требуется установленный JDK. Android Studio поставляется со встроенной версией JetBrains Runtime, но при отдельной установке Gradle убедитесь, что в системе есть JDK и корректно настроена переменная JAVA_HOME. Конкретные требования к версии Java зависят от версии Gradle — сверяйтесь с официальной матрицей совместимости.
Настройка Gradle внутри Android Studio
После установки (или при использовании Wrapper) стоит проверить, какую версию использует IDE. Откройте настройки через File → Settings (на macOS — Android Studio → Preferences), затем перейдите в раздел Build, Execution, Deployment → Build Tools → Gradle.
Здесь можно выбрать, какой JDK используется для запуска Gradle, а также указать режим работы — локальная установка или Wrapper. Если вы установили Gradle вручную и хотите использовать именно его, выберите соответствующий пункт и укажите путь к папке установки.
☑️ Проверка настройки Gradle в Android Studio
Отдельно обратите внимание на файл gradle-wrapper.properties. Строка distributionUrl определяет, какая версия Gradle будет скачана для проекта. Менять её вручную стоит только если вы уверены в совместимости с версией Android Gradle Plugin.
Совместимость версий Gradle и Android Gradle Plugin
Одна из самых частых причин проблем — несовместимость версий. Каждая версия Android Gradle Plugin рассчитана на определённый диапазон версий Gradle, и нарушение этого соответствия приводит к ошибкам сборки.
| Компонент | Где задаётся | За что отвечает |
|---|---|---|
| Gradle | gradle-wrapper.properties |
Ядро системы сборки |
| Android Gradle Plugin | build.gradle (уровень проекта) |
Связка Gradle с Android SDK |
| Gradle JDK | Настройки Android Studio | Java-окружение для запуска сборки |
| Compile SDK | build.gradle (уровень модуля) |
Версия Android API для компиляции |
Точную таблицу соответствия версий Gradle и Android Gradle Plugin всегда проверяйте в официальной документации для разработчиков Android — она регулярно обновляется, и данные из старых статей быстро устаревают.
Типичные ошибки и их решение
Даже при правильной установке синхронизация иногда завершается ошибкой. Разберём распространённые сценарии.
Ошибка скачивания дистрибутива. Если Gradle не загружается, проверьте интернет-соединение и настройки прокси в File → Settings → Appearance & Behavior → System Settings → HTTP Proxy. В корпоративных сетях без указания прокси скачивание может блокироваться.
Конфликт версий Java. Сообщения вроде «Unsupported class file major version» обычно указывают, что версия Gradle не поддерживает используемый JDK. Решение — сменить Gradle JDK в настройках или обновить версию Gradle в Wrapper.
Повреждённый кеш. Если сборка раньше работала, а теперь падает без видимых причин, попробуйте File → Invalidate Caches / Restart. В более тяжёлых случаях помогает удаление папки кеша Gradle в домашней директории пользователя — после этого зависимости скачаются заново.
⚠️ Внимание: перед удалением кеша Gradle учтите, что при следующей синхронизации все зависимости будут скачиваться заново — это может занять заметное время при медленном соединении.
Что делать, если проект требует старую версию Gradle
Если вы открыли устаревший проект, не спешите обновлять всё подряд. Сначала посмотрите версию в gradle-wrapper.properties и сравните её с требованиями вашей версии Android Studio. Иногда проще дождаться автоматической загрузки старой версии Gradle, чем мигрировать проект на новую — особенно если в нём используются устаревшие конструкции в скриптах сборки.
Gradle в командной строке
После установки и настройки полезно уметь работать с Gradle через терминал — это ускоряет диагностику проблем. Основные команды выполняются из корня проекта:
gradlew assembleDebug
gradlew clean
gradlew build
На Windows вместо gradlew используйте gradlew.bat. Обратите внимание: вызывается именно Wrapper проекта, а не глобально установленный Gradle — так гарантируется, что сборка идёт той версией, которая указана в настройках проекта.
Команда gradlew clean очищает результаты предыдущих сборок и нередко помогает при странных ошибках после переключения веток в системе контроля версий.
Часто задаваемые вопросы
Нужно ли устанавливать Gradle отдельно, если у меня есть Android Studio?
Нет, для обычной разработки в Android Studio отдельная установка не требуется. Gradle Wrapper автоматически скачивает нужную версию при первой синхронизации проекта. Ручная установка оправдана только для работы из командной строки вне проектов или настройки сборочных серверов.
Где Android Studio хранит скачанные версии Gradle?
Дистрибутивы и кеш зависимостей хранятся в папке .gradle в домашней директории пользователя. Точный путь зависит от операционной системы.
Как изменить версию Gradle в проекте?
Откройте файл gradle-wrapper.properties и измените значение distributionUrl на нужную версию, затем выполните синхронизацию. Предварительно убедитесь, что новая версия совместима с вашим Android Gradle Plugin — актуальная таблица соответствия есть в официальной документации Android.
Почему синхронизация Gradle занимает очень много времени?
При первом запуске скачивается дистрибутив Gradle и все зависимости проекта — это нормально. Если синхронизация медленная постоянно, проверьте скорость соединения, настройки прокси и не блокирует ли антивирус работу IDE.
Что делать, если Gradle не видит установленный JDK?
Проверьте настройки в разделе Build Tools → Gradle — там можно явно указать Gradle JDK, включая встроенный в Android Studio. Для отдельной установки Gradle проверьте системную переменную JAVA_HOME.