← Назад к блогу

Как настроить прокси в Android Studio и Gradle: gradle.properties и SDK Manager

Разбираем, как правильно прописать прокси в gradle.properties, настроить SDK Manager и Android Studio, а также устранить самые частые ошибки синхронизации Gradle.

📅13 ноября 2026 г.

Если 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 — они дают более реалистичную картину поведения сервисов в разных регионах.