Android 빌드 실패했을 때 확인 리스트

Android 빌드는 iOS보다 설정이 복잡해서 로컬에서는 잘 돌지만 배포 환경에서 실패하는 경우가 많다. 혼자 개발할수록 한 번 실패한 상황을 명확히 기록해야 다음 번에 빠르게 처리할 수 있다.

개발 환경 상태 확인

Flutter doctor로 Android 관련 도구들의 상태를 먼저 체크한다.

flutter doctor -v

출력에서 다음 부분을 특히 봐야 한다:

• Android toolchain: [✓] 있는지 확인
• SDK 버전: compileSdkVersion 버전 번호
• 연결된 디바이스 개수
• 빌드 도구 버전

[!] 표시가 있으면 해당 부분을 먼저 수정해야 한다.

권한 설정 확인

Android 권한은 android/app/src/main/AndroidManifest.xml에 정의된다. 앱이 필요로 하는 권한이 모두 선언되었는지 확인한다.

일반적인 권한들:

• INTERNET: 네트워크 통신
• READ_EXTERNAL_STORAGE, WRITE_EXTERNAL_STORAGE: 파일 접근
• CAMERA, ACCESS_FINE_LOCATION: 센서 접근
• POST_NOTIFICATIONS: 푸시 알림 (Android 13 이상)

권한 없이 기능을 사용하려 하면 앱이 크래시하거나 조용히 실패한다.

빌드 모드 구분

Flutter와 Android 빌드는 debug, release, profile 세 가지 모드가 있다. 각각 다르게 동작할 수 있으니 어떤 모드에서 문제가 발생하는지 먼저 파악한다.

# Debug 모드로 실행
flutter run

# Release 모드로 빌드 (실기기 필요)
flutter run --release

# Profile 모드로 빌드
flutter run --profile

Release 모드에서만 실패한다면 난독화(ProGuard/R8) 때문일 수 있다.

빌드 출력 로그 확인

상세 로그를 보면서 빌드하면 정확히 어느 단계에서 실패하는지 알 수 있다.

flutter run --verbose

로그에서 주목할 부분:

• Gradle 컴파일 에러
• 네이티브 라이브러리 링크 실패
• AndroidX 호환성 문제
• 플러그인 충돌

Gradle 캐시 초기화

가끔 Gradle 캐시 때문에 이전 빌드 상태가 남아 있을 수 있다. 캐시를 지우고 다시 빌드한다.

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

이것만으로도 많은 빌드 문제가 해결된다.

현상 기록

나중에 같은 문제가 생기면 빠르게 참조하도록 다음 정보들을 남겨둔다:

• 정확한 에러 메시지
• 발생한 빌드 모드
• 연결된 디바이스/에뮬레이터 정보
• 시도해본 해결책과 결과