Flutter 빌드 시 놓치기 쉬운 Gradle 설정

Flutter 개발을 시작하면 Gradle 빌드가 실패한다. 에러 메시지는 해석하기 어렵고, 온라인 검색은 잘못된 해결책을 제시한다. 하지만 체계적으로 접근하면 대부분의 빌드 문제는 몇 가지 설정에 불과하다.

먼저 Gradle 상태 확인

flutter doctor -v

이 명령 하나로 많은 정보를 얻는다. Gradle 버전, Java 버전, Android SDK, Kotlin 버전이 모두 표시된다. 만약 Java가 없거나 버전이 맞지 않으면, 빌드가 진행되지 않는다.

권한 문제

chmod +x android/gradlew

Gradlew (Gradle Wrapper)는 실행 파일이어야 한다. Git에서 다운받거나 복사하면 실행 권한이 없을 수 있다.

빌드 모드 이해하기

flutter run --verbose  # Debug 모드 (기본)
flutter run --release  # Release 모드

Debug 모드는 빠르지만 크고, Release 모드는 느리지만 빌드 최적화가 되어 있다. 만약 debug에서는 되는데 release에서 안 되면, 최적화 과정에서 문제가 난 것이다.

실기기 vs 에뮬레이터

flutter devices

연결된 기기를 확인한다. 실기기의 로그는 에뮬레이터와 다를 수 있다. 특히 권한 문제(카메라, 파일 접근)는 실기기에서만 발생할 수 있다.

API 응답 확인

앱이 떴는데 기능이 안 되면, 로그를 본다.

flutter run  # 로그 스트림 보기

"connection refused", "timeout", "permission denied" 같은 키워드를 찾는다. API 응답이 다르면 앱도 예상과 다르게 동작한다.

자주 나오는 빌드 실패 원인

1. Java 버전 불일치

java -version

Android Gradle Plugin 8.0 이상은 Java 17 이상이 필요하다.

2. Gradle 캐시

flutter clean
flutter pub get
flutter run

캐시가 깨졌을 때 해결 방법. 먼저 clean을 하고, 의존성을 다시 받은 후 빌드한다.

3. Kotlin DSL vs Groovy

Gradle 파일이 .kts (Kotlin DSL) 또는 .gradle (Groovy)인지 확인한다. 문법이 다르면 에러난다.

4. 의존성 버전 충돌

pubspec.yaml에서 플러그인 버전이 앱의 SDK 버전과 맞지 않을 수 있다. 특히 카메라, 위치 정보, 결제 같은 플러그인들은 특정 버전 이상의 앱을 요구한다.

flutter pub outdated

오래된 의존성을 확인하고 업그레이드한다.

단계별 빌드 확인

1. flutter doctor -v로 환경 확인
2. flutter clean + flutter pub get으로 캐시 초기화
3. flutter run --verbose로 상세 로그 출력
4. 실패한 지점의 로그를 읽고 원인 파악
5. Gradle 설정 파일(build.gradle) 또는 pubspec.yaml 수정
6. 다시 빌드

한 번에 여러 설정을 바꾸면 복잡해진다. 로그에서 실패한 지점을 정확히 파악한 후, 그 부분만 수정하는 게 빠르다.