Android Gradle 빌드 실패 해결법 - 캐시 클리어부터 의존성 충돌까지

Android Gradle 빌드 실패 해결법

요약: Android Studio에서 Gradle 빌드가 실패할 때 확인해야 할 핵심 해결책들을 정리했습니다.

---

1. Gradle 캐시 완전 삭제

가장 먼저 시도해볼 방법입니다. 캐시가 손상되었거나 오래된 의존성이 문제를 일으킬 수 있습니다.

# 프로젝트 폴더에서 실행
./gradlew clean

# 글로벌 캐시 삭제 (Mac/Linux)
rm -rf ~/.gradle/caches/

# Windows
rd /s /q %USERPROFILE%\.gradle\caches

Android Studio에서는 File > Invalidate Caches / Restart도 함께 실행하면 더 효과적입니다.

2. 의존성 버전 충돌 해결

서로 다른 라이브러리가 같은 라이브러리의 다른 버전을 요구할 때 발생합니다.

// build.gradle에서 의존성 트리 확인
./gradlew app:dependencies

// 특정 버전 강제 지정
configurations.all {
    resolutionStrategy {
        force 'androidx.core:core:1.12.0'
    }
}

3. JDK 버전 불일치

Gradle과 Android Studio가 다른 JDK를 사용하면 빌드 에러가 발생할 수 있습니다.

// gradle.properties에 추가
org.gradle.java.home=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home

Android Studio에서 File > Project Structure > SDK Location에서도 JDK 경로를 확인하세요.

4. 메모리 부족 에러

대규모 프로젝트에서 자주 발생하는 OutOfMemoryError 해결법:

// gradle.properties
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m
org.gradle.parallel=true
org.gradle.caching=true

5. 네트워크/프록시 문제

회사 네트워크나 프록시 환경에서 의존성 다운로드가 실패할 때:

// gradle.properties
systemProp.http.proxyHost=proxy.company.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.company.com
systemProp.https.proxyPort=8080

추가 팁

• Android Studio 최신 버전으로 업데이트
• Gradle 버전과 AGP(Android Gradle Plugin) 버전 호환성 확인
• --stacktrace 옵션으로 상세 에러 로그 확인: ./gradlew build --stacktrace

참고 자료

• Android 공식 빌드 가이드
• Gradle 트러블슈팅 가이드

---

작성: 밤비스