Android эмулятор на macOS

Пошаговое руководство по установке Android SDK, эмулятора и запуску собственного приложения на macOS (Apple Silicon). Подходит для Capacitor-приложений и любых Android-проектов.

Установка через Homebrew

1. Android Command Line Tools

brew install android-commandlinetools

После установки SDK доступен по пути:

/opt/homebrew/share/android-commandlinetools/

2. Android Platform Tools (adb)

brew install android-platform-tools

Проверка:

adb --version

3. Android Studio (опционально)

Если нужен GUI для управления SDK и AVD:

brew install android-studio

Можно обойтись без Android Studio

Для сборки и запуска приложений достаточно command line tools. Android Studio нужна только если хочется визуальный менеджер эмуляторов или IDE для нативного кода.

Настройка ANDROID_HOME

Добавить в ~/.zshrc:

export ANDROID_HOME=/opt/homebrew/share/android-commandlinetools
export PATH="$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"

Применить:

source ~/.zshrc

Проверить:

echo $ANDROID_HOME
# /opt/homebrew/share/android-commandlinetools

Установка SDK компонентов

Принять лицензии

yes | sdkmanager --licenses

Установить платформу, build-tools, system image, эмулятор

sdkmanager "platforms;android-34" "build-tools;34.0.0" "emulator" "system-images;android-34;google_apis;arm64-v8a"

Версии

android-34 — это Android 14 (UpsideDownCake). Для более новых версий замени 34 на нужную. arm64-v8a — для Apple Silicon (M1/M2/M3/M4). На Intel Mac используй x86_64.

Проверить что установлено:

sdkmanager --list_installed

Создание эмулятора (AVD)

Создать виртуальное устройство

avdmanager create avd \
  --name pixel7 \
  --package "system-images;android-34;google_apis;arm64-v8a" \
  --device "pixel_7"

• --name — имя, которым будешь запускать эмулятор
• --device — модель устройства (список: avdmanager list device)

Список созданных AVD

avdmanager list avd

Удалить AVD

avdmanager delete avd --name pixel7

Запуск эмулятора

С графическим окном

export ANDROID_HOME=/opt/homebrew/share/android-commandlinetools
"$ANDROID_HOME/emulator/emulator" -avd pixel7

Без окна (headless, для CI)

"$ANDROID_HOME/emulator/emulator" -avd pixel7 -no-window -no-audio

В фоне

"$ANDROID_HOME/emulator/emulator" -avd pixel7 &

Проверить что эмулятор запущен

adb devices
# List of devices attached
# emulator-5554	device

Статус "offline" или пустой список

Эмулятору нужно 10-30 секунд на загрузку Android. Подожди и повтори adb devices. Если “offline” — подожди ещё.

Сборка и запуск Capacitor-приложения

Предусловия

В проекте должен быть настроен Capacitor:

npm install @capacitor/core @capacitor/cli @capacitor/android

Добавить Android-платформу

npx cap add android

Создаст директорию android/ с Android-проектом.

Собрать web-assets и синхронизировать

npm run build          # Vite/Webpack build
npx cap sync android   # Копирует dist/ в android/app/src/main/assets/public/

cap sync после каждого изменения

После любого изменения в web-коде нужно пересобрать и вызвать cap sync, иначе в APK будет старая версия.

Собрать APK

cd android
./gradlew assembleDebug

APK будет в:

android/app/build/outputs/apk/debug/app-debug.apk

Первая сборка

Первый запуск Gradle скачивает ~500MB зависимостей. Это нормально. Последующие сборки занимают 10-30 секунд.

Установить на эмулятор

adb install android/app/build/outputs/apk/debug/app-debug.apk

Запустить приложение

adb shell am start -n <appId>/.MainActivity

Например:

adb shell am start -n bike.ryazan.tracker/.MainActivity

appId — значение из capacitor.config.ts.

Переустановка после изменений

npm run build && npx cap sync android && cd android && ./gradlew assembleDebug && cd .. && adb install -r android/app/build/outputs/apk/debug/app-debug.apk && adb shell am start -n bike.ryazan.tracker/.MainActivity

Флаг -r при adb install — переустановка поверх существующего.

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

Отладка WebView

Capacitor-приложение — это WebView. Для отладки:

1. Открой Chrome на компьютере
2. Перейди на chrome://inspect/#devices
3. Эмулятор должен появиться в списке
4. Нажми “inspect” рядом с WebView приложения
5. Откроется Chrome DevTools с консолью, сетью, DOM

Если WebView не видно

Убедись что в capacitor.config.ts нет server.androidScheme: 'http' — Chrome inspect работает только с https (дефолт в Capacitor 6+).

Типичные проблемы

”ANDROID_HOME is not set”

Добавь в ~/.zshrc и перезапусти терминал. См. раздел Настройка ANDROID_HOME.

”No installed build tools found"

sdkmanager "build-tools;34.0.0"

"Failed to find Platform SDK with path: platforms;android-34”

sdkmanager "platforms;android-34"

Gradle зависает на первой сборке

Это нормально — скачиваются зависимости. Первая сборка может занять 3-5 минут. Не прерывай.

Два Gradle-процесса конкурируют за lock

Если запустил два ./gradlew параллельно — один зависнет в ожидании lock. Убей лишний:

ps aux | grep gradle-wrapper | grep -v grep
kill <PID старого процесса>