Практическое руководство по Gradle‑сборке и быстрым фиксам

Чтобы собрать Android-проект корректно — настройте корневой и модульный build.gradle, используйте совместимые версии AGP и Gradle, управляйте JVM‑параметрами и кешем. Ниже — компактные инструкции и готовые решения для типичных сбоев.

Структура build.gradle и примеры практической настройки

В проекте два ключевых файла: корневой (Project) и модульный (Module, например app). Корневой объявляет плагины и репозитории, модульный — android {} и зависимости.

Пример корневого (рекомендуемый modern approach с pluginManagement / version catalog):

# gradle/libs.versions.toml
[versions]
agp = "8.5.2"
kotlin = "1.9.22"

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

В settings.gradle.kts подключите catalog и репозитории. В module (app/build.gradle.kts):

android {
  namespace = "com.example.myapp"
  compileSdk = 35
  defaultConfig {
    applicationId = "com.example.myapp"
    minSdk = 24
    targetSdk = 35
    versionCode = 1
    versionName = "1.0"
  }
}
dependencies {
  implementation(libs.kotlin.stdlib)
}

Совет: держите compileSdk и targetSdk на актуальном стабильном уровне — это снижает шум от deprecated-API.

AGP, Gradle и совместимость: как обновлять без сбоев

AGP (Android Gradle Plugin) — мост между Gradle и Android SDK. В 2026 актуальные ветки AGP требуют Gradle 8+. Перед обновлением:

1. Проверьте требуемую минимальную версию Gradle в release notes AGP.
2. Обновите wrapper: ./gradlew wrapper --gradle-version=8.7.
3. Обновите Kotlin и Compose Compiler совместимо с AGP (иногда нужен конкретный kotlinCompilerExtensionVersion).

В CI всегда фиксируйте версии в gradle-wrapper.properties и libs.versions.toml, чтобы сборки были детерминированными.

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

1. Could not resolve dependency — добавьте google(), mavenCentral() и (при необходимости) maven { url 'https://s01.oss.sonatype.org/content/repositories/snapshots/' }. Очистите кэш: ./gradlew cleanBuildCache.
2. OutOfMemoryError — в gradle.properties:

org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8
org.gradle.parallel=true
org.gradle.caching=true

3. Несовместимость AGP/Gradle — следуйте сообщению об ошибке "Minimum supported Gradle version is X.Y" и обновите wrapper.
4. R8/ProGuard не минифицирует — проверьте proguard-rules.pro и включите minifyEnabled true в buildTypes.release.
5. Медленная сборка с Compose — используйте подходящую версию Compose Compiler, jvmToolchain(17) и включите org.gradle.configuration-cache=true.

Частые ошибки

• Неправильно указанные репозитории (jcenter вместо mavenCentral).
• Конфликты версий библиотек (решается через implementation("x:y:version") и forcedResolution в extreme cases).
• Игнорирование configuration cache и build cache.
• Использование устаревших плагинов с новым AGP.

FAQ

• Как быстро узнать требуемую версию Gradle для AGP?
  Читайте release notes AGP в changelog; если нет — смотрите сообщение об ошибке при сборке и обновляйте wrapper.

• Нужно ли всегда обновлять AGP до последней версии?
  Риск есть: сначала проверьте совместимость Kotlin/Compose и тестируйте в CI на feature branch.

• Как ускорить сборку в CI?
  Кэшируйте ~/.gradle/caches и .gradle, используйте Gradle Daemon (если позволяет среда) и configuration cache.

Если после применения этих шагов сборка всё ещё ломается — приложите --stacktrace --info вывод сборки и ищите конкретные строки ошибок: большинство проблем решается по тексту исключения.