Ошибка Android SDK not found при первой сборке проекта почти всегда означает, что toolchain — цепочка инструментов разработки под Android — установлен не полностью или путь к нему не прописан в переменных окружения. Проверьте наличие каталога SDK и значение переменной ANDROID_HOME до переустановки чего-либо: в большинстве случаев проблема решается правильной настройкой путей.
Android toolchain — это набор компонентов, без которых невозможно собрать, отладить и установить приложение на устройство: Android SDK, SDK Platform-Tools с утилитой ADB, компиляторы, при необходимости Android NDK для нативного кода и система сборки Gradle. Ниже разберём, что входит в toolchain, как его установить и настроить, а также какие ошибки встречаются чаще всего.
Что входит в Android toolchain
Цепочка инструментов разработки под Android состоит из нескольких обязательных и опциональных компонентов. Понимание роли каждого из них избавит от ситуации, когда «всё установлено, но ничего не собирается».
- 🧰 Android SDK — платформенные библиотеки, заголовочные файлы и образы системы для конкретных уровней API.
- 🔧 SDK Build-Tools — компиляторы ресурсов и утилиты упаковки APK/AAB.
- 📱 SDK Platform-Tools — утилиты ADB и fastboot для связи с устройством.
- ⚙️ Android NDK — набор для сборки нативного кода на C/C++, нужен не всем проектам.
- 🏗️ Gradle + Android Gradle Plugin — система сборки, связывающая всё воедино.
- 💻 Android Studio — официальная IDE, которая умеет ставить перечисленное автоматически.
Отдельно упомянем JDK: сборка Android-проектов требует Java-машины. Современные версии Android Studio поставляются со встроенным JDK, поэтому отдельная установка обычно не нужна, если вы не собираете проект из командной строки с собственной Java.
⚠️ Внимание: версии SDK Platform, Build-Tools и Android Gradle Plugin должны быть совместимы между собой. Несовместимость — частая причина ошибок сборки вида
Unsupported class file major versionили конфликтовcompileSdkVersion. Требуемые версии указаны в документации к используемой версии Gradle-плагина.
Установка Android SDK и Platform-Tools
Самый простой путь — установить Android Studio с официального сайта разработчиков Android. Во время первого запуска мастер предложит скачать SDK, Platform-Tools и эмулятор. Это закрывает потребности большинства разработчиков без ручной настройки.
Если IDE не нужна (например, вы настраиваете сборочный сервер), используйте консольный менеджер sdkmanager из пакета command line tools. Типовая последовательность выглядит так:
sdkmanager --install "platform-tools" "platforms;android-34" "build-tools;34.0.0"Конкретные версии платформы и build-tools зависят от требований вашего проекта — их можно посмотреть в файле build.gradle модуля приложения. После установки принять лицензии можно командой sdkmanager --licenses.
Настройка переменных окружения
Чтобы утилиты toolchain были доступны из любого терминала, необходимо указать системе, где лежит SDK. Для этого создаётся переменная окружения ANDROID_HOME, указывающая на корневой каталог SDK, а в PATH добавляются каталоги с исполняемыми файлами.
- 🖥️ Windows: «Параметры → Система → О системе → Дополнительные параметры системы → Переменные среды».
- 🐧 Linux/macOS: строки экспорта добавляются в
~/.bashrcили~/.zshrc.
Пример для Unix-подобных систем:
export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin
После правки файла перезапустите терминал или выполните source ~/.zshrc. Проверка проста: команда adb version должна вывести версию утилиты, а не ошибку «команда не найдена».
☑️ Проверка готовности toolchain
Подключение устройства и проверка ADB
Чтобы устанавливать и отлаживать приложения на реальном смартфоне, на нём нужно включить отладку по USB. Для этого сначала активируется скрытое меню «Для разработчиков»: в настройках телефона откройте раздел «О телефоне» и несколько раз нажмите на пункт «Номер сборки». Точное расположение пунктов зависит от оболочки производителя, поэтому при расхождениях сверяйтесь с инструкцией к вашей модели.
После подключения кабеля выполните:
adb devicesЕсли устройство отображается со статусом unauthorized, на экране смартфона нужно подтвердить разрешение на отладку с этого компьютера. Статус offline или пустой список чаще всего означает проблему с кабелем, драйвером (актуально для Windows, где может потребоваться USB-драйвер производителя) или тем, что отладка не включена.
Для отладки по Wi-Fi (Android 11 и выше) кабель после первичного сопряжения не нужен — устройство и ПК должны находиться в одной сети. Это удобно, когда USB-порт занят или кабель нестабилен.
NDK и нативная разработка
Android NDK требуется, когда часть логики пишется на C или C++: игровые движки, обработка аудио/видео, переносимые библиотеки. Устанавливается NDK через SDK Manager в Android Studio или командой sdkmanager --install "ndk;версия". Версию NDK проект обычно фиксирует в build.gradle, чтобы сборка была воспроизводимой на разных машинах.
Для сборки нативного кода используется CMake или ndk-build. Важно понимать: NDK собирает библиотеки под конкретные ABI (arm64-v8a, armeabi-v7a, x86_64), и набор поддерживаемых архитектур задаётся в конфигурации проекта. Если приложение падает с ошибкой UnsatisfiedLinkError на конкретном устройстве, вероятная причина — отсутствие библиотеки под его ABI.
Какие ABI поддерживать в 2020-х
Большинство современных устройств работают на arm64-v8a. Архитектура x86_64 нужна в основном для эмуляторов и отдельных устройств. Google Play требует наличия 64-битных версий библиотек при публикации. Точные требования стоит проверять в актуальной документации Google Play.
Типичные ошибки toolchain и их решение
Большая часть проблем с toolchain сводится к нескольким повторяющимся сценариям. Ниже — сводная таблица для быстрой диагностики.
| Симптом | Вероятная причина | Что проверить |
|---|---|---|
SDK location not found | Не задан путь к SDK | Файл local.properties или ANDROID_HOME |
adb: command not found | Platform-Tools нет в PATH | Переменная PATH, наличие каталога platform-tools |
Устройство unauthorized | Не подтверждён RSA-ключ | Диалог разрешения на экране телефона |
| Ошибка лицензий SDK | Лицензии не приняты | Запустить sdkmanager --licenses |
| Конфликт версий Gradle/AGP | Несовместимые версии плагина и Gradle | Таблицу совместимости в документации AGP |
⚠️ Внимание: не скачивайте SDK, NDK и драйверы с сторонних сайтов и «сборок». Используйте только официальные источники — сайт разработчиков Android и SDK Manager. Модифицированные инструменты могут содержать вредоносный код и подменять собранные приложения.
Полезные практики при работе с toolchain
Фиксируйте версии инструментов в проекте: compileSdk, minSdk, версию Gradle и AGP. Это гарантирует, что проект соберётся одинаково на вашей машине и на CI-сервере. Обновления toolchain лучше выполнять осознанно, читая список изменений, а не «по привычке» — мажорные обновления AGP иногда требуют правок в конфигурации сборки.
Для командной работы полезно держать в репозитории Gradle Wrapper (файлы gradlew и gradle-wrapper.properties) — тогда участникам не нужно вручную ставить конкретную версию Gradle, она скачается автоматически при первой сборке.
Часто задаваемые вопросы
Можно ли разрабатывать под Android без Android Studio?
Да. Достаточно установить command line tools, SDK, Platform-Tools и использовать Gradle из терминала. IDE удобнее, но не обязательна — сборка и установка APK полностью выполняются командами.
Чем SDK отличается от NDK?
SDK предназначен для разработки на Java/Kotlin и содержит платформенные API Android. NDK нужен для нативного кода на C/C++ и требуется далеко не в каждом проекте.
Устройство не определяется через ADB на Windows. Что делать?
Проверьте кабель (некоторые кабели передают только питание), включённую отладку по USB и наличие USB-драйвера производителя устройства. В диспетчере устройств аппарат не должен отображаться с ошибкой.
Нужно ли обновлять Build-Tools при обновлении SDK Platform?
Обычно да: версии build-tools и целевой платформы связаны между собой. Требуемые версии проект указывает в конфигурации Gradle, а SDK Manager подскажет недостающие компоненты при синхронизации.
Как проверить, что toolchain настроен полностью?
Выполните adb version, sdkmanager --list_installed и соберите тестовый проект командой ./gradlew assembleDebug. Успешная сборка и установка APK на устройство — итоговое подтверждение, что цепочка инструментов работает.