Dev Note

Flutter 릴리스 빌드만 스플래시에서 멈출 때: 리소스 축소가 지운 알림 아이콘

경품·이벤트 소식을 알림으로 알려 주는 안드로이드 앱(경품 레이더)을 Flutter로 만들 때 일입니다. flutter run으로 띄운 디버그 빌드도, 성능을 보려고 만든 프로파일 빌드도 멀쩡했는데, 릴리스 APK만 스플래시 화면에서 더 나아가지 않았습니다. 크래시 대화상자도 없고 앱이 꺼지지도 않았습니다.

원인은 Android의 리소스 축소(isShrinkResources)였습니다. Dart 코드에서 문자열로만 이름을 넘긴 알림 아이콘을 축소기가 안 쓰는 리소스로 보고 지웠고, 아이콘을 못 찾은 flutter_local_notifications 초기화가 runApp 앞에서 예외를 던졌습니다.

배경: 리소스 축소를 켠 이유

Play Console은 2027년 2월부터 메모리 표준을 넘는 앱의 공개 상태나 게시 기능을 제한할 수 있다고 예고했고, 그 기준 하나가 R8 같은 도구로 얻는 DEX 최적화 커버리지 25% 이상입니다. 스튜디오의 다른 앱들도 차례로 R8을 켜던 중이라, 이 앱은 첫 커밋부터 R8과 리소스 축소를 켰습니다.

buildTypes {
    release {
        // (서명 설정 생략)
        // Play 메모리 표준(DEX 최적화 25% 이상) — R8 최적화 + 리소스 축소
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(
            getDefaultProguardFile("proguard-android-optimize.txt"),
            "proguard-rules.pro",
        )
    }
}

사실 이 두 줄을 쓰지 않아도 Flutter 앱의 릴리스 빌드는 대개 이미 리소스를 축소하고 있습니다. 뒤에서 다시 다룹니다.

크래시가 아니라 첫 프레임이 없는 것

릴리스 전용 문제라면 R8이 리플렉션용 클래스를 지운 경우를 먼저 떠올리지만, 그런 문제는 대개 프로세스가 죽으며 크래시로 남습니다. 이번에는 프로세스가 살아 있었으니, Dart 쪽에서 무언가 실패해 첫 프레임까지 못 갔다고 보는 편이 맞습니다.

Flutter 템플릿의 LaunchTheme은 창 배경으로 launch_background를 깔고, 템플릿 주석대로 이 배경은 엔진이 첫 프레임을 그릴 때 사라집니다. 스플래시에서 멈춘다는 건 첫 프레임이 없다는 뜻이고, 그렇다면 runApp이 불렸는지부터 봐야 합니다. 당시 main()은 이랬습니다.

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final controller = AppController();
  await Notifier.init(onTap: (url) {
    if (url != null) controller.openFromNotification(url);
  });
  await Workmanager().initialize(callbackDispatcher);
  await registerBackgroundPoll();
  runApp(PrizeRadarApp(controller: controller));
  // ...
}

알림 초기화와 백그라운드 작업 등록을 모두 기다린 뒤에야 runApp을 부릅니다. 하나라도 예외를 던지면 main()의 Future가 실패로 끝나고 runApp에는 끝내 닿지 못합니다. Dart의 처리되지 않은 비동기 예외는 프로세스를 죽이지 않습니다. 엔진이 로그 한 줄을 남길 뿐이고, 시스템은 이것을 크래시로 보지 않습니다.

진단 1: logcat의 flutter 태그

릴리스 빌드에서도 처리되지 않은 Dart 예외는 logcat에 flutter 태그로 찍힙니다.

flutter build apk --release
adb install -r build/app/outputs/flutter-apk/app-release.apk
adb logcat -s flutter

앱을 띄우면 아래 모양의 줄이 나옵니다. 메시지는 플러그인 소스에 있는 문구 그대로입니다(읽기 좋게 줄을 나눴습니다).

E flutter : [ERROR:flutter/runtime/dart_vm_initializer.cc(..)] Unhandled Exception:
PlatformException(invalid_icon, The resource @drawable/ic_stat_radar could not be found.
Please make sure it has been added as a drawable resource to your Android head project., null, null)

알림 초기화에서 넘긴 값은 이것이었습니다.

await _plugin.initialize(
  settings: const InitializationSettings(
    android: AndroidInitializationSettings('@drawable/ic_stat_radar'),
  ),
  // ...
);

에러 코드 invalid_icon을 플러그인의 안드로이드 소스에서 찾으면 이 지점이 나옵니다(flutter_local_notifications 22.3.2, 발췌).

private void initialize(MethodCall call, Result result) {
  Map<String, Object> arguments = call.arguments();
  String defaultIcon = (String) arguments.get(DEFAULT_ICON);
  if (!isValidDrawableResource(
      applicationContext, defaultIcon, result, INVALID_ICON_ERROR_CODE)) {
    return;
  }
  // ...
}
private static boolean isValidDrawableResource(
    Context context, String name, Result result, String errorCode) {
  int resourceId = context.getResources().getIdentifier(name, DRAWABLE, context.getPackageName());
  if (resourceId == 0) {
    result.error(errorCode, String.format(INVALID_DRAWABLE_RESOURCE_ERROR_MESSAGE, name), null);
    return false;
  }
  return true;
}

Dart에서 넘긴 이름이 메서드 채널을 타고 Resources.getIdentifier()에 그대로 들어가고, 그 이름의 리소스가 없으면 0이 돌아와 초기화가 곧바로 실패합니다. 아이콘 파일은 res/drawable/ic_stat_radar.xml에 분명히 있었으니, 남은 질문은 빌드 결과물에도 있느냐였습니다.

진단 2: 파일 목록 말고 리소스 테이블을 본다

APK를 zip으로 열어 파일 이름을 찾는 방법은 릴리스 빌드에서 믿을 수 없습니다. 디버그 APK와 릴리스 APK를 비교하면 이렇습니다(고친 뒤 빌드의 출력입니다).

$ unzip -l app-debug.apk | grep ic_stat_radar
     1064  01-01-1981 01:01   res/drawable/ic_stat_radar.xml
$ unzip -l app-release.apk | grep ic_stat_radar
(출력 없음)
$ aapt2 dump resources app-release.apk | grep -A1 "drawable/ic_stat_radar"
    resource 0x7f070082 drawable/ic_stat_radar
      () (file) res/K2.xml type=XML

릴리스 APK에서는 리소스 파일 경로가 res/K2.xml처럼 짧게 바뀌어 있어서, 리소스가 살아 있어도 파일 목록에서는 보이지 않습니다. 판단은 aapt2 dump resources가 보여 주는 리소스 테이블로 해야 합니다. aapt2는 Android SDK의 build-tools/<버전>/ 아래에 있습니다. getIdentifier()가 0을 돌려줬다는 것은 이 테이블에 그 이름의 항목이 없었다는 뜻입니다.

AAB는 더 조심해야 합니다. 나중에 다른 앱에서 확인해 보니 AAB의 리소스 테이블에는 지워진 리소스 이름이 원본 경로 문자열로 남아 있어, 문자열 검색으로는 판별되지 않았습니다. resource 0x… type/name 줄을 정확히 맞춰 비교해야 합니다.

축소기의 판단 기록: resources.txt

축소기가 무엇을 남기고 지웠는지는 build/app/outputs/mapping/release/resources.txt에 남습니다. 앞부분에 이번 문제의 핵심이 있습니다.

android.content.res.Resources#getIdentifier present: true
Web content present: true
Referenced Strings:
cancel
Rap
callerContext
...
Marking drawable:admob_close_button_black_circle_white_cross:2131165270 used because it matches string pool constant admob

축소기는 코드에 getIdentifier() 호출이 있다는 것을 알고(present: true), 코드의 문자열 상수(Referenced Strings)를 리소스 이름과 맞춰 봅니다. admob이라는 상수 때문에 admob_으로 시작하는 drawable을 살려 뒀다는 기록도 보입니다. 그런데 이 문자열 목록 어디에도 ic_stat_radar는 없습니다.

근본 원인: 축소기는 Dart 코드를 읽지 못한다

축소기가 리소스를 쓰인다고 보는 근거는 코드의 리소스 ID 참조(R.drawable.ic_xxx), 매니페스트·레이아웃 같은 XML의 참조, keep 파일입니다. 기본값인 안전 모드에서는 공식 문서 설명대로, 동적으로 불러올 리소스 이름을 만드는 데 쓰일 법한 문자열 상수가 있으면 그 리소스도 도달 가능한 것으로 표시될 수 있습니다. 위의 admob 기록이 그 흔적입니다.

문제는 여기서 말하는 코드가 DEX, 곧 Java·Kotlin 바이트코드라는 점입니다. Flutter 릴리스 빌드에서 Dart 코드는 AOT 컴파일되어 libapp.so라는 네이티브 라이브러리에 들어갑니다. 릴리스 APK를 풀어 문자열을 찾아보면 위치가 분명히 갈립니다.

$ strings -a lib/arm64-v8a/libapp.so | grep ic_stat_radar
@drawable/ic_stat_radar
$ strings -a classes.dex classes2.dex | grep -c ic_stat_radar
0

아이콘 이름은 libapp.so에만 있고 DEX에는 한 번도 나오지 않습니다. 이 아이콘에 이르는 경로는 "Dart 문자열 → 메서드 채널 → 플러그인의 getIdentifier()" 하나뿐인데, 이 경로는 실행 중에만 존재합니다. 빌드 시점의 축소기에게는 아무도 가리키지 않는 drawable이었고, 규칙대로 지웠습니다. 축소기가 틀린 게 아니라, 판단에 필요한 정보가 축소기가 읽을 수 없는 곳에 있었습니다.

런처 아이콘을 쓰면 괜찮아 보이는 이유

알림 아이콘으로 @mipmap/ic_launcher를 넘기면 이 문제가 드러나지 않습니다. 매니페스트의 android:icon이 같은 리소스를 가리켜 살아남기 때문인데, 알림 쪽 참조를 알아본 게 아니라 우연입니다. 라이트온 AI 노트가 이렇게 쓰고 있어서, 런처 아이콘 이름을 바꾸는 순간 알림이 조용히 깨지지 않도록 그 앱에도 keep 파일을 넣었습니다. 반대로 상태 표시줄용 단색 아이콘을 따로 만드는 정석을 따를수록 이 함정에 바로 걸립니다. 플러그인 README도 릴리스 빌드에서는 알림 아이콘을 keep 파일로 남기라고 안내합니다.

디버그와 프로파일에서 재현되지 않는 이유

디버그 빌드는 리소스를 축소하지 않습니다. 의외였던 건 프로파일입니다. Flutter Gradle 플러그인 소스(FlutterPlugin.kt)는 profile 빌드 타입을 initWith(debug)로 만듭니다. Dart는 AOT로 컴파일돼도 안드로이드 빌드 설정은 디버그의 복사본이라 R8도 리소스 축소도 돌지 않습니다. 실제로 프로파일 APK에는 아이콘이 원래 경로 그대로 들어 있었습니다.

같은 파일에서 릴리스 쪽 동작도 보입니다. Flutter 3.47.9 기준으로 이 플러그인은 앱이 덮어쓰지 않는 한 release 빌드 타입에 isMinifyEnabled = true와 isShrinkResources = true를 넣고, flutter build의 --no-shrink 플래그는 도움말에 효과가 없다고 적혀 있습니다. 축소 설정을 적지 않은 Flutter 앱도 릴리스에서는 이미 리소스를 줄이고 있습니다.

고친 방법

1. res/raw/keep.xml로 남길 리소스를 알려 준다

<?xml version="1.0" encoding="utf-8"?>
<!-- 알림 아이콘은 Dart 에서 이름(문자열)으로만 참조해 리소스 축소가 지워 버린다 — 릴리스에서 유지 -->
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@drawable/ic_stat_radar" />

tools:keep에는 남길 리소스를 쉼표로 나열하고 @drawable/ic_stat_*처럼 와일드카드도 쓸 수 있습니다. 공식 문서에 따르면 keep 파일 자체는 앱에 패키징되지 않고, 전역으로 적용되니 패키지 이름을 넣은 고유한 파일 이름을 쓰라고 권합니다. 플러그인 예제 앱은 drawable 전부를 남기지만, 아이콘이 몇 개뿐이라면 이름을 적는 쪽이 낭비가 적습니다.

2. 부가 기능의 초기화가 앱 시작을 막지 않게 한다

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final controller = AppController();
  // 알림·백그라운드 작업 설정이 실패해도 앱은 떠야 한다
  try {
    await Notifier.init(onTap: (url) {
      if (url != null) controller.openFromNotification(url);
    });
  } catch (e) {
    debugPrint('알림 초기화 실패: $e');
  }
  try {
    await Workmanager().initialize(callbackDispatcher);
    await registerBackgroundPoll();
  } catch (e) {
    debugPrint('백그라운드 작업 등록 실패: $e');
  }
  runApp(PrizeRadarApp(controller: controller));
  await controller.start();
  final launchUrl = await Notifier.launchPayload().catchError((_) => null);
  if (launchUrl != null) unawaited(controller.openFromNotification(launchUrl));
  unawaited(Ads.init());
}

keep 파일이 원인을 고친다면, 이 수정은 다음 사고의 크기를 줄입니다. 초기화가 예외를 잡고 있었다면 이번 일도 "앱이 안 열린다"가 아니라 "알림이 안 온다"로 끝났을 겁니다. 알림을 눌러 실행됐는지 확인하는 launchPayload()도 같은 플러그인을 타므로 catchError로 감쌌습니다. 다만 try/catch만 넣고 keep 파일을 빠뜨리면 증상이 조용해질 뿐이니, 둘은 함께 들어가야 합니다.

검증

다시 만든 릴리스 APK의 리소스 테이블에 drawable/ic_stat_radar가 돌아왔고, resources.txt에서는 참조와 상관없이 살려 두는 The root reachable resources are: 목록에 올라 있었습니다. keep 파일 자체(raw:keep)는 Unused resources are: 쪽에 있어 문서대로 패키징되지 않았습니다. 다시 설치한 릴리스 APK는 스플래시를 지나 정상적으로 시작했습니다.

같은 함정이 숨어 있는 다른 자리

조건은 두 가지입니다. 리소스를 이름으로 찾고, 그 이름이 축소기가 읽지 못하는 곳(Dart 코드, 서버 응답, 설정 파일)에 있는 경우입니다. Flutter에서는 플러그인이 메서드 채널로 이름을 받아 네이티브에서 getIdentifier()를 부르는 구조가 전형입니다.

flutter_local_notifications의 다른 인자

알림마다 지정하는 icon, DrawableResourceAndroidBitmap으로 넘기는 큰 아이콘, BigPicture 스타일의 drawable, RawResourceAndroidNotificationSound로 넘기는 알림음도 모두 이름으로 조회됩니다. 알림음은 raw 타입으로 찾고, 없으면 invalid_sound 에러를 돌려줍니다. README는 최악의 경우 알림이 조용히 안 뜰 수 있다고 경고합니다.

audio_service: 플러그인이 자기 리소스를 이름으로 찾는다

음악 앱 송빗에서 겪은 경우는 더 까다로웠습니다. audio_service는 미디어 컨트롤 아이콘을 Dart 쪽에서 이름으로 지정하고, 그 아이콘 PNG는 플러그인이 직접 들고 있습니다.

// audio_service (Dart) — 미디어 컨트롤 아이콘을 이름으로 지정
androidIcon: 'drawable/audio_service_play_arrow',
// audio_service (Java) — "type/name" 을 잘라 이름으로 조회
int getResourceId(String resource) {
    String[] parts = resource.split("/");
    String resourceType = parts[0];
    String resourceName = parts[1];
    return getResources().getIdentifier(resourceName, resourceType, getApplicationContext().getPackageName());
}

AGP 9로 올린 빌드를 태블릿에서 확인해 보니 소리는 나는데 알림창에 미디어 컨트롤이 없었고, 상태가 바뀔 때마다 You must specify an icon resource id to build a CustomAction이 찍혔습니다. AGP 9에서 기본으로 켜지는 최적화된 리소스 축소가 이전 버전이 남기던 리소스 444개를 더 지웠고, audio_service 아이콘 일곱 개가 모두 그 안에 있었습니다. 전에 살아 있었다는 사실은 아무것도 보장하지 않았습니다.

이때는 keep 목록 대신 최적화된 리소스 축소를 껐습니다. keep 목록은 이름을 아는 조회만 막을 수 있는데 Google 라이브러리는 소스가 닫혀 있고, 로그인과 결제를 새 도구 체인에서 아직 시험하지 못했기 때문입니다. 대가는 APK 약 250KB였습니다.

# AGP 9 turns on R8's optimized resource shrinking. It cannot see resources found by name at runtime,
# so it removed every audio_service icon (the names are in Dart) and 1.8.40 (74) lost its media controls.
android.r8.optimizedResourceShrinking=false

대신 이름으로 찾는 리소스 아홉 개(audio_service 아이콘, mipmap/ic_launcher, Google 로그인 플러그인이 찾는 string/default_web_client_id)를 목록으로 적고, 릴리스 빌드 끝에 aapt2로 테이블을 읽어 하나라도 빠지면 빌드가 실패하게 했습니다.

빌드 도구가 올라갈수록 범위가 넓어진다

Android 문서에 따르면 AGP 9.0부터는 isShrinkResources = true만으로 최적화된 리소스 축소가 적용되고, AGP 9.3의 새 optimization { enable = true } DSL은 코드와 리소스 최적화를 한 번에 켭니다. 새 DSL에서는 코드 최적화를 켜면 리소스 축소가 기본으로 따라오는 구조입니다.

출시 전 체크리스트

  1. Dart 코드에서 리소스 이름 문자열을 찾는다. '@drawable/…', 'mipmap/…', 'raw/…' 같은 리터럴이 가리키는 리소스는 축소기가 보지 못합니다.
  2. 쓰는 플러그인의 안드로이드 소스에서 getIdentifier()를 찾는다. 플러그인이 자기 리소스를 찾는 경우는 앱 코드에 드러나지 않습니다. 소스가 닫힌 라이브러리는 이렇게 볼 수 없습니다.
  3. 찾은 이름을 res/raw/keep.xml에 적는다. 런처 아이콘을 알림에 쓰고 있어도 적어 둡니다.
  4. 릴리스 산출물의 리소스 테이블로 확인한다. zip 파일 목록이 아니라 aapt2 dump resources의 type/name 항목으로 보고, 가능하면 빌드 단계에 넣습니다.
  5. runApp 앞의 await를 줄인다. 앱이 뜨는 데 꼭 필요하지 않은 초기화는 예외를 잡거나 runApp 뒤로 옮깁니다.
  6. 출시 전에 릴리스 APK를 기기에서 한 번 띄운다. 멈추면 adb logcat -s flutter부터 봅니다.
# Dart 코드에 박힌 리소스 이름 찾기
grep -rnE "'@?(drawable|mipmap|raw)/[a-z0-9_]+'" lib
# 이 프로젝트가 실제로 쓰는 플러그인의 안드로이드 소스에서 이름 조회 찾기 (예시)
python3 - <<'EOF'
import json, pathlib, subprocess
from urllib.parse import urlparse, unquote
cfg = json.load(open('.dart_tool/package_config.json'))
for p in cfg['packages']:
    uri = p['rootUri']
    if not uri.startswith('file://'):
        continue
    src = pathlib.Path(unquote(urlparse(uri).path)) / 'android' / 'src'
    if src.exists():
        subprocess.run(['grep', '-rnE', r'\.getIdentifier\(', str(src)])
EOF

패턴을 .getIdentifier(로 좁힌 것은 getIdentifier만으로 찾으면 webview_flutter_android의 getIdentifierForStrongReference처럼 리소스와 무관한 이름도 걸리기 때문입니다. 걸린 줄은 열어서 조회하는 이름이 어디서 오는지 확인해야 합니다.

남는 교훈

축소기는 자기가 읽을 수 있는 코드만 믿습니다. Flutter 앱의 로직은 대부분 그 바깥, libapp.so에 있습니다. 리소스를 이름으로 넘기는 순간 그 연결은 빌드 도구에게 보이지 않으니, 사람이 keep 파일로 적어 줘야 합니다.

"디버그에서 된다"는 릴리스에 대해 아무것도 말해 주지 않습니다. 프로파일조차 안드로이드 쪽 설정은 디버그의 복사본이었습니다. 릴리스에서만 켜지는 단계가 있다면, 그 단계를 거친 산출물을 한 번은 직접 실행해 봐야 합니다.

한 줄 요약 — Dart에서 문자열로 넘기는 Android 리소스 이름은 리소스 축소기가 보지 못합니다. res/raw/keep.xml의 tools:keep에 적고, 출시 전에 릴리스 APK를 기기에서 한 번 띄워 보세요.
← 블로그 목록으로