Flutter 프로젝트에서 Gradle 빌드가 실패할 때

Gradle 빌드가 실패했다면, 처음부터 정답을 맞히려고 하면 오히려 확인 시간이 길어진다.

핵심은 현재 상태를 정확히 파악하고, 문제를 하나씩 좁혀나가는 것이다. 실기기 로그, 의존성, 환경 설정을 눈으로 확인할 수 있는 값부터 모은다.

Flutter 상태 확인

먼저 Flutter 환경이 제대로 설정되어 있나 확인한다.

flutter doctor -v
flutter run --verbose

flutter doctor는 모든 의존성이 설정되어 있나 보여준다. 안드로이드 SDK, Java, Gradle 버전이 맞는지 확인할 수 있다.

Gradle 버전 확인

Gradle 버전이 프로젝트와 맞지 않으면 빌드가 실패한다. 프로젝트의 Gradle 설정을 확인하고, 필요하면 업데이트한다.

로컬과 CI/CD 환경에서 Gradle 버전이 다를 수도 있다.

권한 확인

빌드에 실패했다면, 바로 수정하기 전에 권한부터 확인하면 불필요한 변경을 줄일 수 있다.

• 먼저 볼 것: 실기기 로그와 Flutter doctor 출력
• 비교할 것: 정상일 때의 모바일 앱 빌드 상태
• 기록할 것: 명령어, 빌드 로그, 수정한 설정

빌드 모드 확인

디버그 모드와 릴리스 모드에서 다르게 동작할 수 있다. 빌드 모드를 명확히 하고, 같은 모드에서 다시 빌드해본다.

검증

1. 같은 조건에서 에러가 다시 나타나나 확인한다.
2. 로그에서 뭐가 달라졌는지 정확히 설명한다.
3. 실제로 앱을 설치하고 실기기에서 실행해본다.

Gradle 문제는 대부분 버전이나 설정 문제다. 결과가 바뀐 이유를 로그로 설명할 수 있으면 충분히 정리된 것이다.