Flutter로 Android 빌드할 때 막힐 때 원인 좁히는 순서

Flutter의 Android 빌드는 Gradle, Android SDK, 자바 버전 같은 여러 레이어가 얽혀 있어서, 에러 메시지가 복잡하고 이해하기 어려울 때가 많다. 하지만 체계적으로 접근하면 대부분 몇 가지 원인 중 하나다.

먼저 flutter doctor로 환경을 확인한다

flutter doctor -v

이 명령은 Flutter, Dart, Android SDK, 자바, 그레이들 버전을 모두 확인해준다. 에러나 경고가 있다면 먼저 여기서 해결해야 한다.

특히 주의할 점:

• Android SDK는 최신이어야 한다 (API 34 이상)
• Java는 11 이상이어야 한다 (Flutter 3.0+ 기준)
• Gradle이 설치되지 않았거나 너무 오래된 버전이면 문제가 생긴다

Release 빌드와 Debug 빌드를 구분한다

Debug 빌드는 로컬 테스트용이고, Release 빌드는 배포용이다. 각각 문제가 다를 수 있다:

# Debug 빌드 (개발 중)
flutter build apk --debug

# Release 빌드 (배포)
flutter build apk --release

# App Bundle (Google Play)
flutter build appbundle --release

Debug 빌드가 성공해도 Release 빌드가 실패할 수 있다. 특히 키 서명(signing) 설정이 Release에만 필요하다.

Gradle 에러를 읽는 방법

Gradle 빌드 실패 메시지는 보통 이렇게 생겼다:

FAILURE: Build failed with an exception.

* What went wrong:
Task 'compileDebugJavaWithJavac' failed with an exception.

"What went wrong" 다음 줄이 핵심이다. 그 아래의 스택 트레이스는 나중에 봐도 된다.

흔한 실수들:

# 1. Java 버전 미스매치
# -> 에러: "Could not find method implementation() for arguments [com.example:lib:1.0]"
# -> 해결: Java 11+ 버전 확인

# 2. 그레이들 버전 호환 문제
# -> 에러: "Minimum supported Gradle version is 6.7"
# -> 해결: android/gradle/wrapper/gradle-wrapper.properties 에서 버전 업그레이드

# 3. 빌드 캐시 문제
# -> 해결: flutter clean && flutter pub get

로컬 테스트로 문제를 재현한다

Gradle 에러의 대부분은 로컬에서도 발생한다. 먼저 로컬 환경에서만 테스트하자:

flutter clean
flutter pub get
flutter run -v  # verbose 플래그로 상세 로그 보기

-v 플래그를 쓰면 모든 명령어가 실행되는 과정을 볼 수 있다.

그래도 안 되면 Android Studio에서 직접 빌드한다

Flutter CLI 대신 Android Studio의 Build 메뉴에서 빌드하면, IDE의 에러 표시가 더 명확할 때가 있다:

open -a "Android Studio" android/
# 또는 명령줄에서
./gradlew build  # android 폴더에서 실행

에러 메시지가 더 자세할 수 있다.

의존성 충돌 확인

플러그인들이 같은 라이브러리의 다른 버전을 요구할 때 충돌한다:

flutter pub get
flutter pub tree  # 의존성 트리 출력

pubspec.lock 파일을 보면 설치된 정확한 버전을 알 수 있다. 플러그인 업데이트로 이런 충돌을 해결할 때가 많다:

flutter pub upgrade camera  # 특정 패키지만 업그레이드
flutter pub upgrade          # 모든 패키지 업그레이드

키 서명 설정 (Release 빌드)

Release 빌드는 반드시 서명해야 한다. 키가 없으면 만들고:

keytool -genkey -v -keystore ~/key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload

그 후 android/key.properties 파일을 만들어서:

storePassword=<password>
keyPassword=<password>
keyAlias=upload
storeFile=<path-to-key.jks>

캐시 정리가 필수

빌드 실패했을 때 가장 먼저 해야 할 일:

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

이 순서대로 하면 대부분 문제가 해결된다. Gradle과 Flutter의 캐시가 오래되면 이상한 에러가 많이 생기기 때문이다.

문제를 정확히 파악하려면 한 번에 하나씩만 바꾸는 게 중요하다. 여러 개를 동시에 수정하면 뭐가 원인인지 알 수 없다.