Gradle Offline Mode: причины ошибки и способы включения

Что означает ошибка Gradle Offline Mode

Ошибка Gradle Offline Mode возникает, когда Android Studio работает в офлайн-режиме, но Gradle не может найти необходимые зависимости в локальном кэше. В результате сборка проекта прерывается с сообщением, похожим на:

Could not resolve all files for configuration ':app:debugRuntimeClasspath'.
> Could not find com.android.tools.build:gradle:8.2.0.
  Required by:
      project :app

Этот режим полезен для работы без интернета, но требует, чтобы все артефакты (библиотеки, плагины) были предварительно загружены. Ошибка появляется при первом запуске нового проекта, после очистки кэша или при изменении версий зависимостей.

Причины возникновения

1. Включён офлайн-режим в настройках Gradle — Gradle игнорирует онлайн-репозитории и ищет артефакты только в локальном кэше.
2. Отсутствуют кэшированные зависимости — например, после установки Android Studio или при использовании нового компьютера.
3. Повреждённый локальный кэш Gradle — файлы в кэше (~/.gradle/caches) повреждены или неполны.
4. Конфликт версий зависимостей — в build.gradle указана версия библиотеки, которой нет в локальном кэше.
5. Некорректные настройки прокси — Gradle не может подключиться к репозиториям из-за блокировки брандмауэром или неправильного прокси.

Способы решения

Способ 1: Отключение Offline Mode

Самый простой способ — отключить офлайн-режим в настройках Android Studio.

1. Откройте File → Settings (для macOS: Android Studio → Preferences).
2. Перейдите в Build, Execution, Deployment → Gradle.
3. В разделе Gradle settings снимите галочку с Offline work.
4. Нажмите OK.
5. Синхронизируйте проект, нажав кнопку Sync Project with Gradle Files (значок слонёнка в панели инструментов).

После этого Gradle сможет загружать недостающие зависимости из интернета.

Способ 2: Принудительная синхронизация проектов

Если отключение режима не помогло, выполните принудительную синхронизацию с очисткой предыдущих конфигураций.

1. Убедитесь, что Offline Mode отключён (см. Способ 1).
2. Закройте проект (File → Close Project).
3. Удалите папку .gradle в корне вашего проекта (она будет создана заново).
4. Откройте проект снова.
5. Нажмите Sync Project with Gradle Files.
6. Дождитесь завершения загрузки зависимостей.

⚠️ Важно: Удаление папки .gradle в проекте не затрагивает глобальный кэш (~/.gradle), поэтому не повредит другим проектам.

Способ 3: Очистка глобального кэша Gradle

Иногда проблема кроется в повреждённом глобальном кэше. Его очистка заставит Gradle перезагрузить все зависимости.

1. Закройте Android Studio.
2. Откройте терминал (cmd, PowerShell или Bash).
3. Выполните команду:

   gradle --stop
   rm -rf ~/.gradle/caches/
   

   Для Windows используйте:

   gradle --stop
   rd /s /q %USERPROFILE%\.gradle\caches
   

4. Запустите Android Studio снова.
5. Откройте проект и синхронизируйте его.

💡 Совет: Если у вас несколько проектов, они начнут загружать зависимости заново, что займёт время в зависимости от скорости интернета.

Способ 4: Проверка настроек прокси и сети

Gradle может не подключаться к репозиториям из-за проблем с сетью или прокси.

1. Проверьте подключение к интернету — откройте браузер и зайдите на https://repo.maven.apache.org.
2. В Android Studio откройте File → Settings → Appearance & Behavior → System Settings → HTTP Proxy.
3. Выберите No proxy (если работаете в локальной сети) или укажите корректные параметры прокси.
4. Нажмите Check connection и введите https://repo.maven.apache.org — должно быть сообщение "Connection successful".
5. Если используется корпоративный прокси, убедитесь, что в gradle.properties (в папке ~/.gradle/ или проекта) прописаны настройки:

   systemProp.http.proxyHost=ваш_прокси
   systemProp.http.proxyPort=порт
   systemProp.https.proxyHost=ваш_прокси
   systemProp.https.proxyPort=порт
   

6. Перезапустите Android Studio и синхронизируйте проект.

Способ 5: Обновление Gradle и Android Gradle Plugin

Устаревшие версии Gradle или AGP могут некорректно работать с офлайн-режимом.

1. Откройте файл build.gradle (Project level).
2. Проверьте версии:

   dependencies {
       classpath 'com.android.tools.build:gradle:8.2.0' // AGP версия
   }
   

3. В файле gradle/wrapper/gradle-wrapper.properties укажите актуальную версию Gradle:

   distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip
   

4. Синхронизируйте проект — Android Studio предложит обновить при необходимости.
5. После обновления повторите сборку.

Профилактика

• Не включайте Offline Mode без необходимости — оставляйте его отключённым, чтобы Gradle автоматически обновлял зависимости.
• Регулярно обновляйте зависимости — используйте актуальные версии библиотек в build.gradle, чтобы избежать конфликтов.
• Используйте стабильный интернет — при работе с новыми проектами убедитесь в наличии подключения к сети.
• Не удаляйте вручную файлы из кэша Gradle — это может привести к повреждению. Для очистки используйте команды или настройки Android Studio.
• Настройте кэширование в корпоративной сети — если вы разработчик в компании, попросите администратора настроить локальный репозиторий (Nexus, Artifactory), чтобы сократить зависимость от интернета.

Эти меры помогут избежать повторения ошибки Gradle Offline Mode и обеспечат стабильную сборку проектов.