이전 목록으로
#Flutter#Android

Flutter Android 빌드 버전 호환성: JDK·Gradle·AGP·Kotlin 연결 구조

Flutter 패키지 하나를 올렸을 뿐인데 갑자기 Android 빌드가 깨졌다. 처음에는 Gradle만 올리면 될 줄 알았는데 JDK, AGP, Kotlin, Android SDK와 NDK가 줄줄이 연결되어 있었다. 각 도구의 역할과 버전 충돌을 추적한 순서를 정리한다.

Flutter 앱을 만들고 있으니 Dart와 Flutter 버전만 잘 맞으면 되는 줄 알았다. 그치만 Android 빌드는 마지막에 Java·Kotlin과 Gradle 생태계를 통과한다.

그래서 pubspec.yaml의 패키지 하나만 올렸는데도 갑자기 AGP가 낮다거나 JDK 버전이 맞지 않는다는 오류가 튀어나온다. 하나씩 보면 전혀 다른 도구인데, 빌드할 때는 꽤 단단하게 엮여 있다.

문제가 생길 때마다 전부 최신 버전으로 올리는 건 해결책이 아니었다. 일단 누가 누구를 실행하고, 어디에서 버전을 확인해야 하는지부터 정리해 봤다.

구성 요소의 역할

구성 요소 역할 주로 확인할 위치
JDK Java 컴파일러와 JVM 제공 java -version
Gradle 전체 빌드 작업 실행 gradle-wrapper.properties
AGP Gradle에서 Android 앱을 빌드 settings.gradle.kts
Kotlin Plugin Kotlin 소스 컴파일 settings.gradle.kts
Android SDK Android API와 빌드 도구 compileSdk, targetSdk
NDK C/C++ 네이티브 코드 빌드 ndkVersion
flowchart LR
    A[Flutter CLI] --> B[Gradle Wrapper]
    C[JDK] --> B
    B --> D[Android Gradle Plugin]
    D --> E[Kotlin Plugin]
    D --> F[Android SDK]
    D --> G[NDK와 Native Plugin]
    E --> H[APK 또는 AAB]
    F --> H
    G --> H

여기서 중요한 건 각 버전이 따로 놀지 않는다는 점이다. AGP에는 요구하는 Gradle과 JDK 범위가 있고, 네이티브 코드가 포함된 Flutter 플러그인은 특정 compileSdk나 NDK를 요구하기도 한다.

그러니까 오류에 Gradle이라는 단어가 보인다고 Gradle만 냅다 올리면 안 된다. 그다음에는 AGP가 안 맞고, 또 그다음에는 JDK에서 막히는 식으로 일이 커질 수 있다.

프로젝트에서 버전 찾기

문제를 해결하기 전에 현재 프로젝트가 실제로 어떤 버전을 쓰고 있는지 먼저 남겨두는 편이 좋다. 느낌상 최신 버전 말고, 명령어와 설정 파일에 찍히는 값을 확인한다.

flutter --version
dart --version
java -version
./gradlew -version
flutter doctor -v
// android/settings.gradle.kts
plugins {
    id("com.android.application") version "<AGP_VERSION>" apply false
    id("org.jetbrains.kotlin.android") version "<KOTLIN_VERSION>" apply false
}
# android/gradle/wrapper/gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-<VERSION>-bin.zip
// android/app/build.gradle.kts
android {
    compileSdk = <COMPILE_SDK>
    ndkVersion = "<NDK_VERSION>"

    defaultConfig {
        minSdk = <MIN_SDK>
        targetSdk = <TARGET_SDK>
    }
}

오류를 읽는 순서

예를 들어 다음 메시지가 나왔다고 하자.

Dependency 'androidx.core:core-ktx:...' requires
Android Gradle plugin X or higher.
This build currently uses Android Gradle plugin Y.

처음 보면 Gradle을 올리라는 이야기처럼 보인다. 하지만 이 메시지의 핵심은 라이브러리가 요구하는 AGP보다 프로젝트의 AGP가 낮다는 것이다.

Gradle과 AGP는 이름부터 비슷해서 자꾸 헷갈린다. 둘은 같은 것이 아니다. AGP는 Android 빌드 규칙을 제공하는 플러그인이고, Gradle은 그 작업을 실행하는 빌드 도구다.

나는 다음 순서로 확인하는 것이 가장 덜 꼬였다.

  1. 오류를 발생시킨 직접·전이 의존성을 찾는다.
  2. 해당 라이브러리의 최소 AGP 요구사항을 확인한다.
  3. AGP를 올릴 경우 필요한 Gradle과 JDK 버전을 확인한다.
  4. Kotlin·compileSdk·NDK까지 영향을 점검한다.
  5. CI와 로컬을 같은 버전으로 맞춘다.
flutter pub deps --style=compact
./gradlew app:dependencies

무작정 캐시부터 지우면 안 되는 이유

빌드가 깨지면 일단 flutter clean부터 치고 싶어진다. 나도 그랬다. 가끔은 진짜 해결되기 때문에 더 습관처럼 쓰게 된다.

그치만 캐시 삭제는 깨진 다운로드나 오래된 산출물에는 효과가 있어도, 호환되지 않는 버전 조합까지 맞춰주지는 않는다. AGP 8이 필요한 라이브러리를 AGP 7로 빌드하고 있다면 캐시를 몇 번 지워도 결과는 똑같다.

그래서 먼저 오류 메시지와 현재 버전을 기록한다. 버전 조합에 문제가 없다고 확인한 뒤에야 캐시를 의심하는 편이 낫다.

flutter clean
flutter pub get
cd android
./gradlew clean

팀 체크리스트

한 명의 로컬 환경에서만 성공하면 결국 CI나 다른 팀원의 PC에서 다시 터진다. 아래 항목은 한 번 맞춘 뒤 프로젝트 설정으로 고정해 두는 것이 마음 편하다.

  • Flutter SDK 버전을 프로젝트 단위로 고정했다.
  • pubspec.lock을 커밋한다.
  • CI의 JDK 버전이 로컬과 같다.
  • Gradle Wrapper를 사용한다.
  • AGP를 올리기 전에 공식 호환표를 확인한다.
  • 네이티브 플러그인 업데이트 시 compileSdk·NDK 요구사항을 확인한다.

마무리

Flutter Android 빌드 오류는 에러 메시지에 등장한 도구 하나만 바꿔서는 잘 해결되지 않았다. 결국 중요한 건 의존 관계를 따라가며 현재 조합을 확인하는 것이었다.

정리하면 다음 순서다.

  1. 오류를 요구사항 그대로 읽는다.
  2. Flutter·JDK·Gradle·AGP·Kotlin 버전을 기록한다.
  3. 직접 의존성과 전이 의존성을 확인한다.
  4. 공식 호환 범위 안에서 필요한 항목만 변경한다.
  5. 로컬과 CI에서 같은 환경으로 다시 빌드한다.

캐시 삭제는 마지막에 해도 늦지 않다. 버전이 안 맞는데 빌드 폴더만 열심히 지우고 있었던 시간을 생각하면, 처음부터 표를 하나 만들어 놓는 게 훨씬 빨랐다.

관련 문서

목록으로 돌아가기

다른 게시글

#Android#Flutter

현장 Flutter 앱 디버깅에 자주 쓴 ADB 명령어

기기 지정, Logcat, APK 설치, 파일 복사, 포트 reverse를 실기기 점검 흐름으로 정리한다.

#Android#Kotlin

Android 입력 장치 목록 조회하기: 키보드·마우스·HID 스캐너 구분

Android `InputManager`와 `InputDevice` API로 연결된 입력 장치를 조회하고, 키보드·포인터·외부 장치 여부를 판별하는 방법을 정리한다. USB·Bluetooth HID 바코드 스캐너를 일반 키보드와 구분할 때의 한계와 연결 변경 감지 방법도 함께 살펴본다.

#Android#Kotlin

Android 위치 권한과 FusedLocationProvider 실전 정리: 현재 위치·지속 추적·GPS 설정

Jetpack Compose 앱에서 Android 위치 권한을 요청하고, Fused Location Provider로 캐시 위치·일회성 현재 위치·지속 위치 업데이트를 처리하는 흐름을 정리한다. Android 12의 대략적·정확한 위치 선택, 백그라운드 위치 정책, GPS 설정 확인과 생명주기 연동까지 예제 코드로 살펴본다.