[Flutter] 안드로이드 15 (API 35) 타깃 SDK 대응 및 빌드 에러 해결 가이드

안녕하세요. 코딩하는 Jay입니다.

구글 플레이(Google Play)에 앱을 출시하거나 업데이트를 진행할 때마다 정기적으로 마주치는 관문이 있습니다. 바로 타깃 SDK(targetSdkVersion) 버전 상향 요구인데요.

구글 정책에 따라 신규 앱과 업데이트 앱 모두 안드로이드 15(API 레벨 35) 타깃 대응이 필수가 되었습니다. 기존에 잘 빌드되던 Flutter 프로젝트의 targetSdkVersion을 35로 올리는 순간, 빌드가 터지거나 런타임 에러를 겪으시는 분들이 많으실 것 같습니다.

오늘은 Flutter 프로젝트에서 안드로이드 15(API 35)를 대응할 때 자주 발생하는 빌드 에러와 필수 수정 사항들을 정리해 보았습니다.

1. build.gradle 기본 설정 변경

가장 먼저 android/app/build.gradle 파일에서 SDK 버전을 35로 상향 조정합니다.

android {
    namespace "kr.jayproject.myapp"
    compileSdk 35

    defaultConfig {
        applicationId "kr.jayproject.myapp"
        minSdkVersion 21
        targetSdkVersion 35
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
    }
}

만약 Flutter 3.x 최신 버전을 쓰고 계시다면 flutter.compileSdkVersion 변수가 자동으로 34 이상을 가리키고 있을 수 있지만, 35 빌드 시 일부 라이브러리와의 충돌을 방지하기 위해 명시적으로 compileSdk 35를 지정해 주는 것이 안전합니다.

2. AGP(Android Gradle Plugin) 및 Gradle 버전 점검

compileSdk 35를 인식하기 위해서는 AGP 버전이 8.6.0 이상, Gradle 래퍼 버전이 8.7 이상이어야 합니다. 버전이 낮을 경우 compileSdk 35 requires Android Gradle plugin ... 에러가 발생합니다.

• android/settings.gradle (또는 프로젝트 레벨 build.gradle):

plugins {
    id "com.android.application" version "8.6.1" apply false
    id "org.jetbrains.kotlin.android" version "2.0.20" apply false
}

• android/gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-all.zip

3. Edge-to-Edge 강제 적용 대응 (화면 겹침 현상)

안드로이드 15(API 35)부터 가장 크게 체감되는 변경점은 Edge-to-Edge(전체 화면)가 기본값으로 강제 적용된다는 점입니다. 이전에는 상태바(Status bar)와 네비게이션 바 영역을 OS가 알아서 패딩 처리해 주었지만, API 35 타깃에서는 앱 컨텐츠가 상태바 및 홈 제스처 바 밑으로 파고들게 됩니다.

Flutter에서는 SafeArea 위젯을 필수로 감싸주어야 상/하단 UI가 잘리지 않습니다.

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: SafeArea(
      child: Column(
        children: [
          // 상단 헤더 및 본문 컨텐츠
        ],
      ),
    ),
  );
}

만약 MainActivity.kt에서 윈도우 인셋을 강제로 제어하고 있었다면, 관련 코드를 점검해 주셔야 합니다.

4. 16KB 페이지 크기(Page Size) 호환성 체크

안드로이드 15는 고성능 기기를 위해 16KB 메모리 페이지 크기 지원을 시작했습니다. 순수 Dart/Flutter 코드는 문제가 없지만, C/C++ 네이티브 라이브러리(.so 파일)를 포함하는 플러그인(FFmpeg, SQLite 네이티브 바이너리, 일부 미디어/게임 엔진 등)을 사용할 경우 앱 실행 즉시 크래시가 발생할 수 있습니다.

터미널에서 16KB 정렬 여부를 점검할 수 있습니다:

# APK 압축 해제 후 라이브러리 ELF 헤더 확인
llvm-readelf -l build/app/outputs/flutter-apk/app-release.apk | grep -A 1 LOAD

구버전 NDK로 빌드된 써드파티 플러그인이 있다면 최신 버전으로 flutter pub upgrade를 진행해 주셔야 합니다.

5. 자주 마주치는 빌드 에러 요약

에러 메시지	원인	해결 방법
compileSdk 35 requires AGP 8.6+	AGP 구버전 사용	settings.gradle에서 AGP 8.6.1+ 및 Gradle 8.7+ 상향
Duplicate class found in modules	androidx 중복 의존성	gradle.properties에 android.enableJetifier=true 확인
foregroundServiceType 누락	API 34+ 포그라운드 서비스 제약	AndroidManifest.xml에 서비스 타입 명시
UI가 네비게이션 바에 묻힘	Edge-to-Edge 기본 활성화	루트 뷰에 SafeArea 적용

정리

구글 플레이의 타깃 SDK 상향은 매년 반복되는 작업이지만, 안드로이드 15는 Edge-to-Edge 강제와 Gradle 최신화 요구로 인해 손이 조금 더 가는 편입니다.

마감 직전에 급하게 올리기보다는 미리 로컬 빌드와 실기기 테스트를 거쳐두시는 것을 추천드립니다. 참고하세요!