Flutter Android 13 테마 아이콘 오류 - release에서 단색 아이콘이 안 보일 때

Flutter Android 13 adaptive icon과 monochrome 레이어

Android 13 이상에서 테마 아이콘을 지원하려는 Flutter 앱이라면 android:icon만 바꾸는 방식보다 adaptive icon에 monochrome 레이어를 추가하는 선택이 맞다. 테마 아이콘을 쓰지 않는 사용자나 Android 12 이하까지 같은 모양을 유지해야 하는 앱에는 필수 변경이 아니다. 이 문제는 빌드 실패보다 출시 후 런처에서 아이콘이 단색으로 바뀌지 않거나, foreground 이미지가 잘리는 형태로 드러난다.

왜 release에서만 다르게 보이나

Android 13(API 33)부터 사용자가 테마 아이콘을 켜고 런처가 지원하면 adaptive icon의 monochrome 레이어가 배경색에 맞춰 색칠된다. Flutter 프로젝트의 기본 아이콘은 보통 @mipmap/ic_launcher를 가리키지만, 기존 PNG 하나를 교체하는 것만으로는 이 레이어가 생기지 않는다.

특히 debug에서 확인한 아이콘과 Play 설치본이 다르면 다음 값을 분리해서 봐야 한다.

확인 대상 흔한 결과 원인
Android 12 이하 예전 아이콘 legacy PNG 또는 API 26 미만 리소스가 선택됨
Android 13 테마 아이콘 끔 컬러 adaptive 아이콘 foreground/background는 정상
Android 13 테마 아이콘 켬 기본 아이콘·단색 누락 monochrome 레이어 없음
release 설치본 debug와 다른 아이콘 flavor 리소스 또는 application의 icon 경로 불일치

flutter_launcher_icons를 쓰는 설정

이미 이 패키지로 아이콘을 생성하는 프로젝트라면 설정에 세 가지 입력을 분리한다. 아래 코드는 컬러 adaptive icon과 Android 13 테마용 단색 전경을 함께 만들기 위해 필요하다.

flutter_launcher_icons:
  android: true
  ios: true
  image_path: assets/icon/app_icon.png
  adaptive_icon_background: "#FFFFFF"
  adaptive_icon_foreground: assets/icon/app_icon_foreground.png
  adaptive_icon_monochrome: assets/icon/app_icon_monochrome.png

adaptive_icon_background와 adaptive_icon_foreground 중 하나만 넣으면 adaptive icon이 완성되지 않는다. adaptive_icon_monochrome에는 배경이 투명하고 아이콘 형태가 흰색인 이미지를 준비하는 편이 안전하다. 원본 컬러 로고를 그대로 넣으면 테마 색상으로 칠해질 때 외곽 배경까지 아이콘처럼 보일 수 있다.

설정 파일만 고친 뒤 앱을 실행하지 말고 생성 명령과 release 빌드를 분리해 확인한다.

dart run flutter_launcher_icons
flutter clean
flutter build apk --release

직접 리소스를 관리한다면 android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml에 레이어를 선언한다. 이 파일은 API 26 이상에서 선택되므로 Android 12 이하용 PNG를 지우면 안 된다.

<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
    <background android:drawable="@color/ic_launcher_background" />
    <foreground android:drawable="@drawable/ic_launcher_foreground" />
    <monochrome android:drawable="@drawable/ic_launcher_monochrome" />
</adaptive-icon>

여기서 monochrome는 알림 아이콘 설정과 다른 리소스다. 알림 표시줄의 작은 아이콘이 흰색으로 보여야 한다는 이유로 런처 테마 아이콘 파일을 재사용하면, 홈 화면 마스크와 안전 영역이 맞지 않을 수 있다.

출시 전에 확인할 조건

Play에 올리는 release APK 또는 AAB의 application이 실제 생성한 @mipmap/ic_launcher를 가리키는지 확인한다. flavor를 사용한다면 src/release, src/<flavor>에 같은 이름의 리소스가 덮어쓰지 않는지도 본다. 아이콘 생성 패키지를 추가했지만 AndroidManifest의 icon 이름을 별도로 바꿨다면 생성 결과가 사용되지 않는다.

체크 순서는 아래처럼 짧게 고정하면 된다.

Android 공식 문서 기준으로 adaptive icon은 foreground·background 두 레이어가 필요하고, 테마 아이콘을 지원하려면 monochrome 단일 레이어를 추가한다. Flutter 앱의 Android 아이콘도 네이티브 Android 리소스 방식으로 갱신되므로, Dart 코드가 정상이어도 res/mipmap과 Manifest가 틀리면 화면에서 결과가 달라진다. 확인 기준일은 2026년 10월 15일이다.

참고 문서: Android adaptive icons 공식 문서, Flutter 앱 아이콘과 이미지 리소스, flutter_launcher_icons 설정