Android 빌드가 실패할 때 확인하는 순서

처음부터 정답을 맞히려고 하지 말 것

Android 빌드 에러는 구글링하면 백 가지 이상의 해결책이 나온다. "Gradle 캐시 삭제", "NDK 버전 변경", "Kotlin 업그레이드" 같은 것들. 하지만 대부분은 당신의 문제와 무관하다.

먼저 현재 상태를 정확히 파악해야 한다.

Flutter doctor부터 본다

flutter doctor -v

Flutter 환경 전체 상태를 본다. Android SDK, NDK, Gradle, Kotlin 모두 설치되었는가. 특히 주목할 부분:

• Android SDK version: 최신이 아닌지, 특정 기능이 빠져 있지 않은지
• Android NDK version: r23c 이상인가
• Gradle version: 프로젝트 빌드.gradle과 일치하는가

flutter doctor -v | grep -E "SDK|NDK|Gradle|Kotlin"

이 정도만 봐도 90%의 문제가 보인다.

실제 에러 메시지를 본다

flutter run --verbose 2>&1 | tail -100

Verbose 모드로 빌드하면 진짜 에러가 보인다. "FAILURE" 또는 "FAILED" 다음줄이 중요하다.

가장 흔한 에러들:

1. SDK 버전 불일치: Build tools version 34.0.0 requires Android API 34
2. Gradle 버전: Gradle version 8.x requires Java 11+
3. 메모리 부족: java.lang.OutOfMemoryError: Java heap space

빌드 모드 확인

# Release 빌드
flutter build apk --release

# Debug 빌드
flutter build apk --debug

# Profile 빌드
flutter build apk --profile

Debug 빌드는 성공하는데 Release가 실패할 수도 있다. 특히 코드 축소(shrinking)나 최적화 설정이 다르기 때문이다.

Gradle 캐시 청소

검색 결과에서 가장 많이 나오는 해결책이지만, 마지막에 시도할 것이다.

cd android
./gradlew clean
cd ..
flutter pub get
flutter clean
flutter pub get

Gradle 캐시를 완전히 제거하면 다음 빌드가 오래 걸린다. 실제 에러를 파악한 후에 시도한다.

실기기에서 테스트

flutter devices  # 연결된 기기 확인
flutter run -d <device_id> --verbose

에뮬레이터에선 실패하는데 실기기에선 성공할 수 있다. 또는 그 반대일 수도 있다. 여러 환경에서 테스트하면 패턴이 보인다.

의존성 버전 점검

cat pubspec.yaml | grep -E "\[\^]|:\s*any"

Dependency가 유연하게(^, any) 정의되어 있으면, 새 버전이 올라왔을 때 호환성이 깨질 수 있다.

flutter pub upgrade --major-versions

그 전에 현재 버전을 고정한다.

dependencies:
  flutter:
    sdk: flutter
  some_package: '1.2.3'  # ^1.2.3 대신 정확한 버전

Kotlin 버전 확인

grep "ext.kotlin_version" android/build.gradle

Kotlin 버전이 너무 오래되면 최신 Gradle과 호환 안 될 수 있다. 최신 버전은 1.8.x 이상이어야 한다.

최종 진단 순서

1. flutter doctor -v 실행해서 환경 상태 파악
2. flutter run --verbose 실행해서 실제 에러 메시지 읽기
3. Debug와 Release 빌드 따로 시도
4. 에뮬레이터와 실기기에서 따로 시도
5. 의존성 버전 명시
6. 마지막 수단으로 Gradle 캐시 삭제

이 순서대로 따르면 검색 결과에서 무작정 따라 하는 것보다 훨씬 빠르게 원인을 찾을 수 있다.