[Flutter] TargetSDK, Gradle 버전 쉽게 올리는 노하우

개요

Android의 TargetSDK는 1년에 한번씩 업그레이드를 해야한다.

 

수년간 개발자들을 괴롭혀온 Gradle 버전 수정 작업이기 때문에 내 나름대로 쉽게 해결할 수 있는 노하우를 정리하여 문서화를 했다.

 

2025.07월에 작성한 글이라 최신 버전에서는 통하지 않을 수 있음.

---

구성

• AndroidStudio v2025.1.1
• Flutter v3.22.3
• Gradle v7.4
• AGP(Android Gradle Plugin) v7.3.1
• Java v17

 

---

진행

1. 프로젝트의 SDK 버전 먼저 올려보기

 

Android의 app/build.gradle 의 targetSdkVersion, compileSdk를 먼저 올려보기.
나는 34 버전에서 35로 변경을 해봤다.
그리고 바로 빌드 테스트를 해본다.

 

2-A. 빌드가 잘 되면 이상 없음.

만약 버전을 올린 이후 이상이 없다면 더이상 손댈 것이 없다. (이상)

 

2. 빌드오류의 경우 AGP 버전 호환성 체크 (이런게 있으니 훑어보기)

대부분 CompileSDK 버전을 올리면 아주 높은 확률로 오류가 발생함.
이럴때는 보통 Gradle 또는 AGP(Android Gradle Plugin)의 버전 이슈일 경우가 대부분.

 

따라서 AGP(Android Gradle Plugin)을 기준으로 Gradle의 적정 버전을 찾고,

Gradle을 기준으로 Java의 적정 버전을 찾아야 한다.

(SDK 버전 > AGP 버전 > Gradle 버전 > Java 버전 순)

 

• 프로젝트 내의 버전 위치
  SDK: prj/android/app/build.gradle > targetSdkVersion & compileSdk
  AGP: prj/android/settings.gradle > id "com.android.application" version "[AGP버전]" apply false
  Gradle: prj/android/gradle/gradle-wrapper.properties > distributionUrl=https://services.gradle.org/distributions/gradle-[Gradle버전]-all.zip
  Java: 플러터가 바라보는 버전에 따라 다름 (터미널에 flutter doctor -v 로 Android Toolchain부분에서 확인 가능, 또한 플러터가 바라보는 버전 직접 수정 가능)

 

주의!! 버전을 소스 내에서 직접 수정하면 머나먼 노가다의 길을 걸을 수 있음.

 

(추가) 버전 호환성에 대한 참고 문서는 여기서 확인할 수 있음.

AGP에 맞는 Gradle 버전 체크: (https://developer.android.com/build/releases/gradle-plugin?hl=ko#updating-gradle)

Gradle에 맞는 Java버전 체크: (https://docs.gradle.org/current/userguide/compatibility.html)

 

3. 본격적으로 Android Studio의 자체 기능으로 AGP 버전 올리기

AndroidStudio로 프로젝트의 android 네이티브 플랫폼 폴더를 직접 열어보기.

왼쪽 하단에 Build메뉴에서 Gradle Sync가 정상적으로 완료되어야 한다. (오래걸릴 수 있음)

 

그 다음

상단의 Tools > AGP Upgrade Assistant 메뉴를 클릭.

 

나의 경우, SDK35 버전이 Gradle 8.0(현재는 7.4) 이상부터 호환이 되기 때문에 AGP 버전을 8.1.4로 잡아봤다.

천천히 한 단계씩 올리면서 빌드 테스트를 해보면 된다.

(갑자기 AGP버전을 크게 올리면 한번에 맞이하게 될 빌드오류 좀비들이 몰려온다.)

 

이 방법을 추천하는 이유는
AGP 버전이 올라가면서 Gradle 버전도 자동으로 올라가는데,

그로 인한 Native 코드들도 Android Studio가 알아서 변경해주기 때문이다.

아래 사진에 빨간 박스는 업그레이드를 할 경우 수정하게 될 사항들임.

 

덕분에 개발자는 Assistant 기능만을 활용해 Gradle 버전을 올릴때,

Native 코드들의 수정 작업에 할당하는 에너지를 줄일 수 있다. 

(단, 줄여진다고는 했지, 없어진다고는 안함)

 

4. 빌드 테스트

버전 수정이 완료되었다면, --debug 와 --release 모두 빌드해보기.

--release의 경우 proguard 또는 서명문제로 인해 추가적인 빌드오류가 발생할 수 있음.

 

빌드 오류가 발생한다면 표시되는 오류 메시지를 잘 보고 GPT를 통해 잘 대응해보기.
보통 외부 패키지에 의한 오류일 확률이 높긴하다.

내가 작업한 현 시점에서는 inappwebview(앱 내에서 웹표시를 하는 패키지)의 네이티브 코드에서 오류가 발생했다. 최신 버전으로 올리면 해결 가능하나 Flutter 버전도 최신이어야 가능하기 때문에 일단은 해당패키지의 Android 코드를 직접 수정해서 해결을 했다.

 

5. 커밋 후 다른 PC에서 Pull을 한 다음 빌드 테스트 해보기

 

당신의 컴퓨터에서만 마법같이 잘 되는 것일 수 있다.
반드시 다른 PC 환경에서도 특별한 조치 없이 제대로 빌드가 되는지 확인해봐라.

 

이상.

 

참고자료:
https://docs.flutter.dev/release/breaking-changes/android-java-gradle-migration-guide