Если Android Studio «висит» на этапе Gradle sync, SDK Manager не грузит компоненты, а зависимости из Maven Central не скачиваются — в 80% случаев проблема не в коде, а в сетевом окружении. Корпоративный firewall, VPN, блокировка IP репозитория или просто отсутствие прямого доступа к интернету — всё это решается правильной настройкой прокси на трёх уровнях: IDE, Gradle и SDK Manager. Разберём, как прописать прокси корректно и без лишних ошибок синхронизации.
Зачем Android-разработчику нужен прокси
Чаще всего прокси в связке с Android Studio используют в нескольких сценариях. Первый — корпоративная сеть, где прямой выход в интернет закрыт, и весь трафик, включая обращения к google(), mavenCentral() и dl.google.com, обязан идти через прокси-сервер компании. Второй — обход региональных ограничений: некоторые SDK-компоненты, API Google Play Services или сторонние репозитории недоступны напрямую из отдельных стран, и разработчик вынужден маршрутизировать трафик через IP другой геолокации.
Третий сценарий — тестирование geo-зависимого функционала приложения. Если приложение показывает разный контент, цены или рекламу в зависимости от страны пользователя, QA-инженерам и разработчикам нужно эмулировать запросы из нужного региона ещё на этапе сборки и отладки, не дожидаясь релиза. Четвёртый — работа с CI/CD раннерами, которые физически расположены в дата-центрах с ограниченным доступом к определённым сервисам, и прокси становится единственным способом «достучаться» до нужного репозитория или API.
Во всех этих случаях логика одна: Gradle, SDK Manager и сама IDE должны знать адрес, порт и, если нужно, учётные данные прокси-сервера, иначе синхронизация проекта будет падать с таймаутами или ошибками подключения.
Какой тип прокси выбрать для разработки
Для разработки и тестирования важна не столько анонимность, сколько стабильность соединения и низкий процент обрывов во время долгих загрузок (например, Android SDK Platform Tools весят сотни мегабайт). Ниже — сравнение типов прокси применительно к задачам Android-разработчика.
| Тип прокси | Когда использовать | Особенности |
|---|---|---|
| Прокси дата-центров | Загрузка SDK, синхронизация Gradle, CI/CD | Высокая скорость, низкая цена, стабильны для больших загрузок |
| Резидентные прокси | Тестирование geo-зависимого API и контента | IP реальных пользователей, реже блокируются сервисами |
| Мобильные прокси | Тестирование мобильных API и push-уведомлений из конкретной страны | IP операторов связи, максимально близки к реальному мобильному трафику |
Для чистой синхронизации Gradle и скачивания зависимостей разумнее брать прокси дата-центров — они дают стабильную высокую скорость без лишних задержек. Если же задача — проверить, как бэкенд приложения отвечает пользователю из другой страны, лучше подойдут резидентные или мобильные IP.
Настройка прокси в gradle.properties
Файл gradle.properties — основное место, где Gradle ищет настройки прокси для HTTP и HTTPS соединений. Файл может лежать в корне проекта (действует только для него) или в глобальной директории ~/.gradle/gradle.properties (действует для всех проектов на машине). Для постоянной работы через прокси рекомендуется второй вариант.
# ~/.gradle/gradle.properties
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080
# опционально — исключения, которые идут напрямую, минуя прокси
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.corp
После сохранения файла обязательно нажмите File → Sync Project with Gradle Files или значок «слон» на панели инструментов. Если IDE не подхватила изменения автоматически, перезапустите Android Studio — иногда кэш настроек прокси держится до перезапуска процесса Gradle Daemon.
Важный нюанс: параметры systemProp.* действуют именно на уровне JVM, в которой выполняется Gradle, поэтому они влияют не только на скачивание зависимостies, но и на любые сетевые запросы внутри build-скриптов (например, если у вас кастомная Gradle-задача, которая дергает внешний API).
Настройка прокси в самой Android Studio
Помимо Gradle, у IDE есть собственные сетевые настройки — они нужны для работы плагинов, обновлений IDE, проверки лицензий и некоторых фич вроде подсказок из Google. Открыть их можно через File → Settings → Appearance & Behavior → System Settings → HTTP Proxy (на macOS — Android Studio → Preferences).
В открывшемся окне выберите Manual proxy configuration, укажите хост и порт, при необходимости отметьте Proxy authentication и впишите логин с паролем. Там же есть удобная кнопка Check connection — введите тестовый URL (например, https://dl.google.com) и нажмите её, чтобы убедиться, что соединение проходит корректно до того, как запускать полноценную синхронизацию проекта.
Важно понимать разницу
Настройки HTTP Proxy в Settings влияют на саму IDE (плагины, обновления), а параметры в gradle.properties — на процесс сборки Gradle. Это два независимых механизма, и для полноценной работы за прокси обычно нужно настроить оба.
Прокси для SDK Manager
SDK Manager — отдельный компонент, который скачивает платформы Android, build-tools, эмуляторы и системные образы. У него есть собственная конфигурация прокси, которая исторически задаётся через те же системные настройки IDE, но при работе через standalone sdkmanager (CLI-утилиту из командной строки) параметры нужно передавать явно через флаги JVM.
sdkmanager --proxy=http \
--proxy_host=proxy.example.com \
--proxy_port=8080 \
--list
Если sdkmanager запускается через скрипт, можно прописать прокси прямо в переменной окружения JAVA_OPTS, которую читает исполняемый файл:
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
Частая ошибка — настроить прокси в Android Studio, но забыть про standalone-утилиты вроде sdkmanager или avdmanager, которые запускаются отдельным процессом Java и не наследуют настройки IDE автоматически.
Прокси для gradlew и переменные окружения
Если вы собираете проект из терминала через обёртку ./gradlew, минуя IDE (например, в CI/CD или просто по привычке), прокси можно передать прямо в команде без изменения gradle.properties:
./gradlew build \
-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080
Для постоянного использования удобнее задать переменную окружения GRADLE_OPTS в профиле оболочки (.bashrc, .zshrc для Linux/macOS или переменные среды Windows):
export GRADLE_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
Это особенно полезно в CI-раннерах GitHub Actions, GitLab CI или Jenkins, где переменные окружения задаются один раз на уровне job и автоматически подхватываются всеми последующими шагами сборки, без необходимости редактировать файлы проекта.
Типичные ошибки синхронизации и их решение
Разберём самые частые ошибки, с которыми сталкиваются разработчики при настройке прокси, и конкретные шаги по их устранению.
| Ошибка | Причина | Решение |
|---|---|---|
| Connection timed out | Прокси не указан или недоступен | Проверьте host/port в gradle.properties, протестируйте доступность прокси через curl |
| 407 Proxy Authentication Required | Не переданы логин/пароль | Добавьте systemProp.http.proxyUser и systemProp.http.proxyPassword |
| Unable to resolve host | DNS-резолвинг не идёт через прокси | Используйте socksProxyHost вместо http для SOCKS5 с удалённым DNS |
| Could not GET 'https://dl.google.com/...' | Настройки Gradle заданы, а в IDE — нет (или наоборот) | Синхронизируйте настройки в обоих местах: Settings → HTTP Proxy и gradle.properties |
| SSL handshake failed | Прокси перехватывает SSL (корпоративный MITM) | Импортируйте корневой сертификат прокси в cacerts вашей JDK |
Если ошибка возникает именно при скачивании конкретных артефактов Maven (например, androidx.* библиотек), полезно временно включить расширенный лог Gradle командой ./gradlew build --info — в выводе будет видно, на каком именно запросе происходит обрыв соединения и какой код ответа возвращает сервер.
Прокси с авторизацией: логин и пароль
Если прокси требует аутентификацию (это стандартная ситуация для платных прокси-сервисов и корпоративных шлюзов), в gradle.properties нужно добавить ещё две строки:
systemProp.http.proxyUser=myuser
systemProp.http.proxyPassword=mypassword
systemProp.https.proxyUser=myuser
systemProp.https.proxyPassword=mypassword
Хранить пароль прокси в открытом виде в проектном gradle.properties, который попадает в систему контроля версий — плохая практика. Используйте глобальный файл в домашней директории пользователя, который не коммитится в Git, либо передавайте пароль через переменные окружения на этапе CI/CD, чтобы секреты не утекали в репозиторий.
Для сценариев, где требуется ротация IP (например, тестирование лимитов API с разных адресов), удобнее брать прокси-сервисы с готовым пулом адресов и единым логином — тогда ротация настраивается на стороне провайдера, а в gradle.properties меняется только порт сессии, без переписывания конфигурации всего проекта.
Чек-лист диагностики
Если после всех настроек синхронизация всё равно падает, пройдите по порядку следующие пункты:
- Проверьте доступность прокси напрямую командой
curl -x http://proxy.example.com:8080 https://dl.google.com - Убедитесь, что настройки прописаны и в Settings → HTTP Proxy, и в gradle.properties одновременно
- Очистите кэш Gradle:
./gradlew --stopи удалите папку.gradle/caches - Проверьте, что в файле нет лишних пробелов и кавычек вокруг значений host/port
- Если используется SOCKS5 — пропишите socksProxyHost/socksProxyPort вместо http.proxyHost
- Для корпоративных MITM-прокси импортируйте сертификат в хранилище доверенных сертификатов JDK (keytool -import)
- Перезапустите Android Studio и Gradle Daemon после любых изменений в properties-файлах
Заключение
Настройка прокси в Android-разработке — это работа сразу на трёх уровнях: системные настройки Android Studio для самой IDE, параметры systemProp в gradle.properties для процесса сборки, и отдельная конфигурация для standalone-утилит вроде sdkmanager. Большинство ошибок синхронизации возникает именно из-за того, что один из уровней настроен, а другой — забыт, либо из-за отсутствия авторизации на прокси, который её требует.
Если задача — просто стабильно качать зависимости и SDK-компоненты через рабочий прокси, для этого отлично подходят прокси дата-центров — они быстрые и не создают лишних задержек при больших загрузках. А если нужно протестировать, как приложение ведёт себя для пользователя из конкретной страны или с мобильного оператора, присмотритесь к резидентным прокси или мобильным IP — они дают более реалистичную картину поведения сервисов в разных регионах.