<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
   <!-- 피드경로 명시 -->
  <channel>
    <title>   </title>
    <description></description>
    <link>https://colin-ch-flutter.github.io/</link>
    <atom:link href="https://colin-ch-flutter.github.io/feed.xml" rel="self" type="application/rss+xml"/>
    <pubDate>Fri, 20 Nov 2026 02:04:51 +0900</pubDate>
    <lastBuildDate>Fri, 20 Nov 2026 02:04:51 +0900</lastBuildDate>
    <generator>Jekyll v3.10.0</generator>
    
      <item>
        <title>Flutter iOS 27 푸시·딥링크 오류 - UIScene 전환 뒤 AppDelegate 콜백이 사라질 때</title>
        <description>&lt;p&gt;&lt;img src=&quot;https://images.unsplash.com/photo-1551650975-87deedd944c3?auto=format&amp;amp;fit=crop&amp;amp;w=1600&amp;amp;q=80&quot; alt=&quot;Flutter iOS 27 UIScene 전환 뒤 푸시와 딥링크를 점검하는 화면&quot; /&gt;&lt;/p&gt;

&lt;p&gt;이 문제는 Flutter 3.41 이상과 Xcode 27로 빌드하면서 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AppDelegate&lt;/code&gt;에 푸시·딥링크 코드를 직접 넣은 앱에 해당한다. 앱이 실행은 되지만 알림을 눌러도 특정 화면으로 가지 않거나 Universal Link가 홈 화면으로만 열리면 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Info.plist&lt;/code&gt;에 Scene 설정을 복사하는 것보다 콜백의 소유자를 나누는 게 우선이다. 기본 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AppDelegate&lt;/code&gt;를 수정하지 않은 프로젝트는 Flutter의 자동 이전 대상이므로 이 글의 코드를 무작정 추가하지 않는다.&lt;/p&gt;

&lt;h2 id=&quot;왜-실행은-되는데-이벤트만-사라지나&quot;&gt;왜 실행은 되는데 이벤트만 사라지나&lt;/h2&gt;

&lt;p&gt;Xcode 27 SDK에서는 UIKit 앱이 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;UIScene&lt;/code&gt; 수명 주기를 사용해야 한다. Flutter 공식 문서 기준으로 Flutter 3.41부터 기본 iOS 앱은 자동 이전되지만, 커스텀 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AppDelegate&lt;/code&gt;가 있으면 UI 이벤트가 더 이상 예전 application 콜백으로 오지 않을 수 있다. 특히 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;application(_:didFinishLaunchingWithOptions:)&lt;/code&gt;의 launch options만 읽는 딥링크 처리와 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;window&lt;/code&gt;를 직접 만지는 코드가 취약하다.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;확인한 현상&lt;/th&gt;
      &lt;th&gt;실제로 갈린 책임&lt;/th&gt;
      &lt;th&gt;우선 확인할 곳&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;앱 시작 후 바로 종료&lt;/td&gt;
      &lt;td&gt;Scene 미이전 또는 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;window&lt;/code&gt; 강제 캐스팅&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AppDelegate&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Info.plist&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;푸시 탭은 열리지만 목적지 없음&lt;/td&gt;
      &lt;td&gt;알림 응답 처리를 UI 수명 주기에만 연결&lt;/td&gt;
      &lt;td&gt;알림 플러그인 설정과 앱 라우터&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Universal Link가 Safari로 감&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;scene(_:continue:)&lt;/code&gt; 전달 누락 또는 Associated Domains&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SceneDelegate&lt;/code&gt;, AASA 파일&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;일반 실행은 정상&lt;/td&gt;
      &lt;td&gt;프로세스 이벤트와 UI 이벤트가 다른 경로&lt;/td&gt;
      &lt;td&gt;AppDelegate와 SceneDelegate를 따로 로그&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;플러그인-등록-위치를-바꾼다&quot;&gt;플러그인 등록 위치를 바꾼다&lt;/h2&gt;

&lt;p&gt;커스텀 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AppDelegate&lt;/code&gt;에서 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GeneratedPluginRegistrant&lt;/code&gt;를 예전 launch 메서드에만 호출하고 있다면 암시적 Flutter 엔진 초기화 콜백으로 옮긴다. 이 코드는 플러그인 등록이 Scene 연결보다 늦어져 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MissingPluginException&lt;/code&gt;이 나는 앱에서 확인할 기준점이다.&lt;/p&gt;

&lt;div class=&quot;language-swift highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kd&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;Flutter&lt;/span&gt;
&lt;span class=&quot;kd&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;UIKit&lt;/span&gt;

&lt;span class=&quot;kd&quot;&gt;@main&lt;/span&gt;
&lt;span class=&quot;kd&quot;&gt;@objc&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;class&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;AppDelegate&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;FlutterAppDelegate&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;FlutterImplicitEngineDelegate&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;kd&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;didInitializeImplicitFlutterEngine&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;_&lt;/span&gt; &lt;span class=&quot;nv&quot;&gt;engineBridge&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;FlutterImplicitEngineBridge&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;kt&quot;&gt;GeneratedPluginRegistrant&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;register&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
      &lt;span class=&quot;nv&quot;&gt;with&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;engineBridge&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;pluginRegistry&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;실제 Flutter SDK의 프로토콜·브리지 타입이 프로젝트 버전과 다르면 IDE 자동 완성으로 선언을 확인해야 한다. 핵심은 메서드 이름을 외워 복사하는 데 있지 않고, 등록을 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;didFinishLaunching&lt;/code&gt;에만 묶지 않는 데 있다. Flutter 공식 예제는 현재 SDK에서 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FlutterImplicitEngineDelegate&lt;/code&gt;와 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FlutterImplicitEngineBridge&lt;/code&gt;를 기준으로 설명한다.&lt;/p&gt;

&lt;h2 id=&quot;푸시와-딥링크는-각각-로그를-남긴다&quot;&gt;푸시와 딥링크는 각각 로그를 남긴다&lt;/h2&gt;

&lt;p&gt;알림 탭과 Universal Link를 하나의 “앱 열림” 로그로 합치면 원인을 잃는다. 앱이 cold start인지 background 복귀인지도 함께 기록하고, 수신한 URL 또는 notification payload를 라우터에 넘기기 전 한 번만 출력한다. 로그는 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kDebugMode&lt;/code&gt;로 감싸지 않아 TestFlight에서도 확인할 수 있게 한다.&lt;/p&gt;

&lt;div class=&quot;language-swift highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kd&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;scene&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_&lt;/span&gt; &lt;span class=&quot;nv&quot;&gt;scene&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;UIScene&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;continue&lt;/span&gt; &lt;span class=&quot;nv&quot;&gt;userActivity&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;NSUserActivity&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;k&quot;&gt;guard&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;let&lt;/span&gt; &lt;span class=&quot;nv&quot;&gt;url&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;userActivity&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;webpageURL&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
  &lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;[universal-link] &lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;url&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;absoluteString&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;c1&quot;&gt;// Flutter 라우터로 전달할 pending URL을 저장한다.&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;firebase_messaging&lt;/code&gt;이나 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;app_links&lt;/code&gt;를 쓰는 경우에는 플러그인이 Scene 콜백을 지원하는 버전인지 확인한다. 앱에서 같은 이벤트를 직접 받아 플러그인에도 넘기면 cold start에서 두 번 라우팅될 수 있다. 하나의 진입점을 정하고, 로그인 전에는 pending route로 보관한 뒤 인증 완료 시 한 번만 소비하는 편이 안전하다.&lt;/p&gt;

&lt;h2 id=&quot;출시-전-체크리스트&quot;&gt;출시 전 체크리스트&lt;/h2&gt;

&lt;ul class=&quot;task-list&quot;&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter build ios&lt;/code&gt; 출력에 자동 UIScene 이전 성공 여부가 남는다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;커스텀 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AppDelegate&lt;/code&gt;가 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;window&lt;/code&gt;나 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;rootViewController&lt;/code&gt;를 launch 콜백에서 강제 사용하지 않는다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GeneratedPluginRegistrant&lt;/code&gt; 등록 위치가 현재 Flutter SDK의 implicit engine 방식과 맞다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;앱이 종료된 상태에서 푸시 탭, 백그라운드에서 푸시 탭, 실행 중 푸시 탭을 각각 시험했다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;실기기에서 Notes의 Universal Link를 눌렀고, TestFlight 서명 앱으로도 확인했다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;앱 삭제 후 재설치하여 예전 링크 캐시와 pending route가 결과를 오염시키지 않는지 확인했다.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;핵심은 iOS 27 크래시와 이벤트 누락을 같은 문제로 취급하지 않는 것이다. Flutter 3.41의 기본 프로젝트는 자동 이전될 수 있지만, 커스텀 수명 주기·푸시 SDK·딥링크 플러그인을 넣은 앱은 AppDelegate가 프로세스 이벤트를 맡고 SceneDelegate가 UI 이벤트를 전달하도록 나눠야 한다. 공식 기준은 &lt;a href=&quot;https://docs.flutter.dev/release/breaking-changes/uiscenedelegate&quot;&gt;Flutter의 UIScene 이전 안내&lt;/a&gt;와 &lt;a href=&quot;https://docs.flutter.dev/add-to-app/ios/add-flutter-screen&quot;&gt;Flutter iOS add-to-app의 SceneDelegate 설명&lt;/a&gt;에서 확인할 수 있다.&lt;/p&gt;
</description>
        <pubDate>Fri, 20 Nov 2026 00:00:00 +0900</pubDate>
        <link>https://colin-ch-flutter.github.io/2026-11-20/22-00-00-4789860-flutter-ios27-uiscene-push-deeplink/</link>
        <guid isPermaLink="true">https://colin-ch-flutter.github.io/2026-11-20/22-00-00-4789860-flutter-ios27-uiscene-push-deeplink/</guid>
        
        <category>Flutter</category>
        
        <category>iOS</category>
        
        <category>출시</category>
        
        <category>Firebase</category>
        
        <category>CI/CD</category>
        
        
      </item>
    
      <item>
        <title>Flutter iOS 27 흰 화면 오류 - 실기기 Device Support 심볼 준비와 flutter run 복구</title>
        <description>&lt;p&gt;&lt;img src=&quot;https://images.unsplash.com/photo-1551650975-87deedd944c3?auto=format&amp;amp;fit=crop&amp;amp;w=1600&amp;amp;q=80&quot; alt=&quot;Flutter iOS 27 실기기 흰 화면과 Device Support 준비&quot; /&gt;&lt;/p&gt;

&lt;p&gt;iOS 27로 업데이트했거나 새 iPhone을 페어링한 뒤 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter run&lt;/code&gt;이 흰 화면에서 멈춘다면 앱 코드보다 Mac의 Xcode Device Support 심볼 준비 상태를 먼저 확인하는 편이 맞다. Xcode 27과 Flutter 3.50 조합이면 CLI가 준비를 자동 처리하지만, Flutter가 낮거나 준비가 실패한 환경은 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;xcodebuild -prepareDeviceSupport&lt;/code&gt;를 직접 실행해야 한다. TestFlight 출시 앱의 흰 화면에는 이 해결책이 적용되지 않는다.&lt;/p&gt;

&lt;h2 id=&quot;증상이-앱-오류처럼-보이는-이유&quot;&gt;증상이 앱 오류처럼 보이는 이유&lt;/h2&gt;

&lt;p&gt;Flutter 공식 이슈에는 iOS 27 실기기에서 앱이 설치·실행된 뒤 흰 화면으로 멈추고, LLDB가 기기의 shared cache를 찾지 못한다는 경고를 남기는 사례가 기록돼 있다. 새 OS의 디버깅 심볼을 Xcode가 내려받는 동안 Flutter가 Dart VM Service 연결을 기다리는 상황이다. 약 5분 뒤 열릴 수도 있지만, 매번 기다리는 방식은 정상적인 개발 조건이 아니다.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;확인 지점&lt;/th&gt;
      &lt;th&gt;Device Support 문제&lt;/th&gt;
      &lt;th&gt;앱 초기화 문제&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;대상&lt;/td&gt;
      &lt;td&gt;새로 업데이트·페어링한 실기기&lt;/td&gt;
      &lt;td&gt;특정 앱 또는 모든 기기&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;로그 단서&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;libobjc.A.dylib&lt;/code&gt; shared cache 경고&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;main()&lt;/code&gt; 이후 플러그인·네트워크 오류&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;우선 조치&lt;/td&gt;
      &lt;td&gt;Xcode 심볼 준비&lt;/td&gt;
      &lt;td&gt;앱 초기화와 플러그인 분리&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;xcode-심볼을-직접-준비하는-방법&quot;&gt;Xcode 심볼을 직접 준비하는 방법&lt;/h2&gt;

&lt;p&gt;기기의 UDID를 확인한 뒤, Xcode가 설치된 Mac에서 아래 명령을 실행한다. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter devices&lt;/code&gt; 출력의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;id&lt;/code&gt; 값을 사용하면 된다.&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;flutter devices
xcrun xcodebuild &lt;span class=&quot;nt&quot;&gt;-prepareDeviceSupport&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-destination&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;id=기기-UDID&quot;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;명령이 끝날 때까지 USB 연결을 유지하고 iPhone의 잠금도 해제한다. Xcode가 Developer Mode, 컴퓨터 신뢰, 기기 페어링을 요구하면 화면에서 승인한다. 준비가 끝난 뒤 다시 실행한다.&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;flutter clean
flutter pub get
flutter run &lt;span class=&quot;nt&quot;&gt;-d&lt;/span&gt; 기기-UDID
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;여기서 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter clean&lt;/code&gt;은 심볼을 내려받는 핵심 명령이 아니다. 이전 빌드 산출물이 남아 결과를 헷갈리게 할 때만 함께 사용한다. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;prepareDeviceSupport&lt;/code&gt;가 실패했다면 Xcode 선택 경로와 버전을 확인한다.&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;xcode-select &lt;span class=&quot;nt&quot;&gt;-p&lt;/span&gt;
xcodebuild &lt;span class=&quot;nt&quot;&gt;-version&lt;/span&gt;
flutter doctor &lt;span class=&quot;nt&quot;&gt;-v&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h2 id=&quot;flutter-버전에-따른-판단&quot;&gt;Flutter 버전에 따른 판단&lt;/h2&gt;

&lt;p&gt;Flutter 3.50 공식 변경 사항에는 새로 페어링했거나 업데이트한 iPhone에서 CLI가 기기를 자동 준비하고, 준비에 실패하면 안내하도록 바뀐 내용이 포함됐다. 따라서 이 증상이 반복되면 무작정 프로젝트 코드를 고치기보다 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter --version&lt;/code&gt;부터 기록한다.&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;Flutter 3.50 이상: 자동 준비 로그와 실패 원인을 확인하고, 실패 시 수동 명령을 실행한다.&lt;/li&gt;
  &lt;li&gt;이전 버전: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;prepareDeviceSupport&lt;/code&gt;를 직접 실행한 뒤 재현 여부를 비교한다.&lt;/li&gt;
  &lt;li&gt;시뮬레이터만 정상: 실기기 심볼·페어링 문제를 우선 의심한다.&lt;/li&gt;
  &lt;li&gt;TestFlight나 App Store 설치본만 흰 화면: 이 글의 디버깅 심볼 문제로 단정하지 않고 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;main()&lt;/code&gt; 초기화, Firebase 설정, 네이티브 플러그인 로그를 따로 확인한다.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;출시 전 체크는 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;새 iOS 기기 연결 → prepareDeviceSupport 완료 → debug 실행 → release 실행 → 백그라운드 복귀&lt;/code&gt; 순서로 남기는 것이 안전하다. 시뮬레이터에서 화면이 열렸다는 사실만으로 실기기 디버깅 환경이 준비됐다고 볼 수 없다.&lt;/p&gt;

&lt;p&gt;핵심은 흰 화면이 보인다는 결과가 아니라, 앱이 첫 프레임을 못 그린 것인지 Flutter가 디버거 연결을 기다리는 것인지 나누는 데 있다. iOS 27 실기기에서만 오래 멈추고 shared cache 경고가 보이면 Device Support를 준비한 뒤 다시 판단하면 된다.&lt;/p&gt;

&lt;p&gt;참고 문서: &lt;a href=&quot;https://flutter.dev/blog/whats-new-in-flutter-3-50&quot;&gt;Flutter 3.50 변경 사항&lt;/a&gt;, &lt;a href=&quot;https://github.com/flutter/flutter/issues/189284&quot;&gt;Flutter iOS Device Support 관련 이슈&lt;/a&gt;, &lt;a href=&quot;https://docs.flutter.dev/platform-integration/ios/setup&quot;&gt;Flutter iOS 개발 환경 설정&lt;/a&gt;&lt;/p&gt;
</description>
        <pubDate>Thu, 19 Nov 2026 00:00:00 +0900</pubDate>
        <link>https://colin-ch-flutter.github.io/2026-11-19/22-00-00-4777515-flutter-ios27-white-screen-device-support/</link>
        <guid isPermaLink="true">https://colin-ch-flutter.github.io/2026-11-19/22-00-00-4777515-flutter-ios27-white-screen-device-support/</guid>
        
        <category>Flutter</category>
        
        <category>iOS</category>
        
        <category>Xcode</category>
        
        <category>디버깅</category>
        
        <category>출시</category>
        
        
      </item>
    
      <item>
        <title>Flutter Android 14 예약 알림 오류 - exact alarm 권한과 inexact 대체 경로</title>
        <description>&lt;p&gt;&lt;img src=&quot;https://images.unsplash.com/photo-1551650975-87deedd944c3?auto=format&amp;amp;fit=crop&amp;amp;w=1600&amp;amp;q=80&quot; alt=&quot;Flutter Android 14 예약 알림과 exact alarm 권한을 점검하는 개발 화면&quot; /&gt;&lt;/p&gt;

&lt;p&gt;Android 14 이상에서 Flutter 예약 알림이 release 앱에서만 누락된다면 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter_local_notifications&lt;/code&gt;의 코드보다 exact alarm 권한을 먼저 확인해야 한다. 약속 시간에 반드시 울려야 하는 알람 앱은 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SCHEDULE_EXACT_ALARM&lt;/code&gt;을 확인하고 사용자에게 설정 화면을 안내해야 한다. 반대로 단순 리마인더나 동기화 알림이라면 exact 권한을 요구하지 않고 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;inexactAllowWhileIdle&lt;/code&gt;로 낮추는 편이 출시 심사와 사용 경험에 유리하다. 알림 자체를 사용하지 않는 앱에는 이 대응이 필요하지 않다.&lt;/p&gt;

&lt;h2 id=&quot;android-14에서-갑자기-예약이-사라지는-이유&quot;&gt;Android 14에서 갑자기 예약이 사라지는 이유&lt;/h2&gt;

&lt;p&gt;Android 14는 Android 13 이상을 대상으로 새로 설치한 앱의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SCHEDULE_EXACT_ALARM&lt;/code&gt;을 기본 허용하지 않는다. 권한이 없는 상태에서 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;exact&lt;/code&gt; 또는 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;exactAllowWhileIdle&lt;/code&gt; 모드로 예약하면 플러그인이 로그를 남기거나 예약을 만들지 못한다. 앱 업데이트에서는 기존 권한이 유지될 수 있지만, 새 기기로 백업 복원한 경우에는 다시 거부될 수 있다.&lt;/p&gt;

&lt;p&gt;여기서 권한을 두 개로 나눠야 한다.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;문제&lt;/th&gt;
      &lt;th&gt;확인할 권한&lt;/th&gt;
      &lt;th&gt;영향&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;알림을 표시할 수 없음&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;POST_NOTIFICATIONS&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Android 13 이상에서 알림 표시 차단&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;정확한 시각에 예약할 수 없음&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SCHEDULE_EXACT_ALARM&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;exact 예약 실패 또는 취소&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;대략적인 시각이면 충분함&lt;/td&gt;
      &lt;td&gt;없음&lt;/td&gt;
      &lt;td&gt;inexact 예약으로 배터리·권한 요구 감소&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Android 공식 문서 기준으로 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;USE_EXACT_ALARM&lt;/code&gt;은 설치 시 자동 허용되지만 알람·캘린더처럼 제한된 용도와 Play 정책을 전제로 한다. 일반적인 습관 알림이나 IoT 상태 알림에 이 권한을 무조건 추가하는 선택은 피하는 게 안전하다.&lt;/p&gt;

&lt;h2 id=&quot;manifest는-예약-기능을-쓸-때만-추가한다&quot;&gt;Manifest는 예약 기능을 쓸 때만 추가한다&lt;/h2&gt;

&lt;p&gt;예약 알림과 부팅 후 재예약을 사용하는 앱이라면 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;android/app/src/main/AndroidManifest.xml&lt;/code&gt;의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&amp;lt;manifest&amp;gt;&lt;/code&gt; 안에 다음 권한을 둔다. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;POST_NOTIFICATIONS&lt;/code&gt;는 Android 13 이상에서 별도로 런타임 요청해야 한다.&lt;/p&gt;

&lt;div class=&quot;language-xml highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nt&quot;&gt;&amp;lt;uses-permission&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;android:name=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;android.permission.POST_NOTIFICATIONS&quot;&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;/&amp;gt;&lt;/span&gt;
&lt;span class=&quot;nt&quot;&gt;&amp;lt;uses-permission&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;android:name=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;android.permission.RECEIVE_BOOT_COMPLETED&quot;&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;/&amp;gt;&lt;/span&gt;
&lt;span class=&quot;nt&quot;&gt;&amp;lt;uses-permission&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;android:name=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;android.permission.SCHEDULE_EXACT_ALARM&quot;&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;/&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SCHEDULE_EXACT_ALARM&lt;/code&gt;을 선언했다고 허용된 것은 아니다. 사용자가 앱의 기능을 선택한 시점에 권한 상태를 확인하고, 필요할 때만 시스템 설정으로 보낸다. 앱 시작 직후 권한 팝업을 띄우면 알림이 왜 필요한지 설명하기 어렵고 거부율도 높아진다.&lt;/p&gt;

&lt;h2 id=&quot;flutter에서-exact와-fallback을-분리한다&quot;&gt;Flutter에서 exact와 fallback을 분리한다&lt;/h2&gt;

&lt;p&gt;예약 시점에 권한을 확인하지 않고 무조건 exact 모드를 넘기는 것이 흔한 실패 원인이다. 아래 코드는 exact 권한이 있으면 정확한 모드를 사용하고, 없으면 사용자가 선택한 기능에 따라 설정 화면을 안내하거나 inexact 모드로 예약한다.&lt;/p&gt;

&lt;div class=&quot;language-dart highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos;package:flutter_local_notifications/flutter_local_notifications.dart&apos;&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;;&lt;/span&gt;

&lt;span class=&quot;kd&quot;&gt;final&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;notifications&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;FlutterLocalNotificationsPlugin&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;();&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;Future&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;&amp;lt;&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;bool&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;&amp;gt;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ensureExactAlarmAccess&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;async&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;kd&quot;&gt;final&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;android&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;notifications&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;resolvePlatformSpecificImplementation&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;&amp;lt;&lt;/span&gt;
      &lt;span class=&quot;n&quot;&gt;AndroidFlutterLocalNotificationsPlugin&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;&amp;gt;();&lt;/span&gt;

  &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;android&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;kc&quot;&gt;null&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;kc&quot;&gt;false&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;

  &lt;span class=&quot;kd&quot;&gt;final&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;canSchedule&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;android&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;canScheduleExactNotifications&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;??&lt;/span&gt; &lt;span class=&quot;kc&quot;&gt;false&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
  &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;canSchedule&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;kc&quot;&gt;true&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;

  &lt;span class=&quot;c1&quot;&gt;// 사용자가 &apos;정확한 알림&apos;을 선택한 화면에서만 호출한다.&lt;/span&gt;
  &lt;span class=&quot;k&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;android&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;requestExactAlarmsPermission&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;();&lt;/span&gt;
  &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;android&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;canScheduleExactNotifications&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;??&lt;/span&gt; &lt;span class=&quot;kc&quot;&gt;false&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;Future&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;&amp;lt;&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;void&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;&amp;gt;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;scheduleReminder&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;({&lt;/span&gt;&lt;span class=&quot;kd&quot;&gt;required&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;bool&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;mustRingOnTime&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;})&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;async&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;kd&quot;&gt;final&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;exact&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;mustRingOnTime&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ensureExactAlarmAccess&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;();&lt;/span&gt;

  &lt;span class=&quot;k&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;notifications&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;zonedSchedule&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;mi&quot;&gt;1001&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;s&quot;&gt;&apos;예약 알림&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;s&quot;&gt;&apos;설정한 시간이 되었다.&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;nextScheduleTime&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(),&lt;/span&gt;
    &lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;NotificationDetails&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
      &lt;span class=&quot;nl&quot;&gt;android:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AndroidNotificationDetails&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&apos;reminder&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&apos;예약 알림&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;nl&quot;&gt;channelDescription:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos;예약된 알림을 표시한다.&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
      &lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
    &lt;span class=&quot;nl&quot;&gt;androidScheduleMode:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;exact&lt;/span&gt;
        &lt;span class=&quot;o&quot;&gt;?&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AndroidScheduleMode&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;exactAllowWhileIdle&lt;/span&gt;
        &lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AndroidScheduleMode&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;inexactAllowWhileIdle&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;nl&quot;&gt;uiLocalNotificationDateInterpretation:&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;UILocalNotificationDateInterpretation&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;absoluteTime&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;위 예제의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;nextScheduleTime()&lt;/code&gt;은 앱의 시간대 정책에 맞는 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tz.TZDateTime&lt;/code&gt;을 반환해야 한다. 시간대 초기화를 생략하면 권한 문제를 고친 뒤에도 해외 이동이나 서머타임에서 알림 시각이 어긋날 수 있다. 또 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mustRingOnTime&lt;/code&gt;을 단순히 사용자가 켠 “알림 받기” 옵션과 섞지 말고, 정확도가 필요한 기능인지 별도 상태로 저장해야 한다.&lt;/p&gt;

&lt;p&gt;정확한 알림이 아닌 경우에는 inexact가 무료 대안이다. Android는 배터리 절약을 위해 실행 시각을 조정할 수 있으므로 “오전 9시 전후에 동기화 결과를 알려주는” 기능에는 충분하지만, 복약·예약 시작처럼 1분 오차도 허용하지 않는 기능에는 적합하지 않다.&lt;/p&gt;

&lt;h2 id=&quot;출시-전에-재현할-체크리스트&quot;&gt;출시 전에 재현할 체크리스트&lt;/h2&gt;

&lt;ol&gt;
  &lt;li&gt;Android 14 이상 새 설치 상태에서 알림 권한과 exact alarm 접근을 모두 거부한다.&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mustRingOnTime: true&lt;/code&gt;인 기능은 설정 화면으로 이동하고, 복귀 후 권한 상태를 다시 읽는다.&lt;/li&gt;
  &lt;li&gt;권한을 허용하지 않은 상태에서 예약이 예외로 종료되지 않고 inexact 또는 안내 상태로 남는지 확인한다.&lt;/li&gt;
  &lt;li&gt;기기를 재부팅한 뒤 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;RECEIVE_BOOT_COMPLETED&lt;/code&gt;와 플러그인의 재예약 설정을 확인한다.&lt;/li&gt;
  &lt;li&gt;Play App Signing으로 만든 release APK에서 알림 채널, 작은 아이콘, 예약 목록을 확인한다.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;특히 설정 화면에서 돌아온 뒤 기존 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;canScheduleExactNotifications()&lt;/code&gt; 값을 캐시하면 안 된다. Android 공식 흐름도 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;onResume&lt;/code&gt; 시점에 권한을 다시 검사하고, 허용되지 않았으면 대체 경로를 제공하라고 안내한다. 테스트는 설정에서 “알람 및 리마인더” 접근을 끈 뒤 예약하는 방식으로 재현할 수 있다.&lt;/p&gt;

&lt;p&gt;정리하면 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;POST_NOTIFICATIONS&lt;/code&gt;는 표시 권한이고, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SCHEDULE_EXACT_ALARM&lt;/code&gt;은 정확한 예약 권한이다. 두 상태를 분리해 확인하고, exact가 제품 요구사항이 아닐 때는 inexact를 기본값으로 두면 Android 14 출시 후 조용히 사라지는 예약 알림을 줄일 수 있다.&lt;/p&gt;

&lt;p&gt;참고 문서: &lt;a href=&quot;https://developer.android.com/about/versions/14/changes/schedule-exact-alarms&quot;&gt;Android exact alarm 공식 가이드&lt;/a&gt;, &lt;a href=&quot;https://developer.android.com/develop/background-work/services/alarms&quot;&gt;Android 알람 예약 가이드&lt;/a&gt;, &lt;a href=&quot;https://pub.dev/packages/flutter_local_notifications&quot;&gt;flutter_local_notifications Android 설정&lt;/a&gt;&lt;/p&gt;
</description>
        <pubDate>Wed, 18 Nov 2026 00:00:00 +0900</pubDate>
        <link>https://colin-ch-flutter.github.io/2026-11-18/22-00-00-4752825-flutter-android14-exact-alarm-notification/</link>
        <guid isPermaLink="true">https://colin-ch-flutter.github.io/2026-11-18/22-00-00-4752825-flutter-android14-exact-alarm-notification/</guid>
        
        <category>Flutter</category>
        
        <category>Android</category>
        
        <category>배포</category>
        
        <category>알림</category>
        
        <category>flutter_local_notifications</category>
        
        
      </item>
    
      <item>
        <title>Flutter Android Baseline Profile - 출시 앱 첫 실행과 초기 프레임을 줄이는 조건</title>
        <description>&lt;p&gt;&lt;img src=&quot;/images/2026-11-17-flutter-android-baseline-profile.png&quot; alt=&quot;Flutter Android Baseline Profile로 출시 빌드의 첫 실행 경로를 최적화하는 흐름&quot; /&gt;&lt;/p&gt;

&lt;p&gt;이 그림에서 볼 부분은 Flutter 코드가 바로 빨라지는 것이 아니라, Android가 자주 실행할 경로를 미리 컴파일할 수 있도록 release 번들에 프로파일을 넣는 흐름이다.&lt;/p&gt;

&lt;p&gt;Flutter Android 앱의 첫 실행과 초기 화면 전환이 느리다면 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;debug&lt;/code&gt; 위젯부터 줄이기보다 Android Baseline Profile을 검토할 가치가 있다. 다만 이 방법은 &lt;strong&gt;Play에 AAB로 출시하는 앱&lt;/strong&gt;과 반복되는 시작 경로가 있는 앱에 맞는다. 단순 화면 몇 개뿐이거나 내부 APK만 배포하는 앱은 프로파일 생성 비용이 이득보다 클 수 있다.&lt;/p&gt;

&lt;h2 id=&quot;flutter에서-문제가-보이는-지점&quot;&gt;Flutter에서 문제가 보이는 지점&lt;/h2&gt;

&lt;p&gt;Flutter는 Dart 코드를 AOT로 컴파일하지만, 앱 시작에는 Android 런처, 플러그인 초기화, Flutter 엔진 연결, 첫 화면 진입이 함께 들어간다. 그래서 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter run --debug&lt;/code&gt;가 아니라 실제 서명한 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;release&lt;/code&gt; 설치본에서 첫 프레임과 첫 이동을 측정해야 한다. Android 공식 문서 기준 Baseline Profile은 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;baseline.prof&lt;/code&gt;로 패키징되어 ART가 자주 실행할 코드를 설치 시점에 최적화하도록 돕는다.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;조건&lt;/th&gt;
      &lt;th&gt;판단&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Play Store AAB 출시&lt;/td&gt;
      &lt;td&gt;적용 가치가 높다&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;사내 APK·직접 설치만 사용&lt;/td&gt;
      &lt;td&gt;설치 경로에 따라 효과가 늦게 나타날 수 있다&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;첫 실행·로그인·홈 진입이 느림&lt;/td&gt;
      &lt;td&gt;해당 경로를 프로파일 시나리오로 만든다&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Flutter 화면 자체가 무거움&lt;/td&gt;
      &lt;td&gt;Baseline Profile만으로 해결되지 않는다&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;android-모듈을-붙이는-최소-구조&quot;&gt;Android 모듈을 붙이는 최소 구조&lt;/h2&gt;

&lt;p&gt;Android Studio의 Baseline Profile Generator 템플릿을 쓰는 편이 수동 작성보다 안전하다. Android 공식 문서가 안내하는 최소 전제는 AGP 8.0 이상이며, 생성 모듈은 앱에 포함되지 않는 테스트 모듈이다. 아래는 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;android/app&lt;/code&gt;에 플러그인과 생성 모듈 의존성을 연결하는 Kotlin DSL 예시다.&lt;/p&gt;

&lt;div class=&quot;language-kotlin highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;// android/app/build.gradle.kts&lt;/span&gt;
&lt;span class=&quot;nf&quot;&gt;plugins&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;nf&quot;&gt;id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;com.android.application&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;nf&quot;&gt;id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;androidx.baselineprofile&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;nf&quot;&gt;dependencies&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;nf&quot;&gt;implementation&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;androidx.profileinstaller:profileinstaller:1.4.1&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;nf&quot;&gt;baselineProfile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;project&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;:baselineprofile&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;프로파일 생성 테스트에서는 실제 패키지명을 사용해 앱 시작과 핵심 이동을 기록한다. Flutter의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;integration_test&lt;/code&gt; 전체를 그대로 복사하는 것이 아니라, Android Macrobenchmark가 실행할 짧고 반복 가능한 사용자 여정을 고르는 게 핵심이다.&lt;/p&gt;

&lt;div class=&quot;language-kotlin highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nd&quot;&gt;@Test&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;fun&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;startup&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;baselineProfileRule&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;collect&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;packageName&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;com.example.app&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;profileBlock&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;nf&quot;&gt;uiAutomator&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;startApp&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nc&quot;&gt;PACKAGE_NAME&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
        &lt;span class=&quot;c1&quot;&gt;// 로그인 이후 홈처럼 반복되는 핵심 경로를 여기에 추가한다.&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;생성 명령은 프로젝트의 Android 디렉터리에서 실행한다.&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nb&quot;&gt;cd &lt;/span&gt;android
./gradlew :app:generateBaselineProfile
flutter build appbundle &lt;span class=&quot;nt&quot;&gt;--release&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;생성된 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;baseline-prof.txt&lt;/code&gt;를 소스에 보관하는 흐름이라면 변경분을 커밋하고, AAB에 실제 바이너리 프로파일이 들어갔는지도 확인한다.&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;unzip &lt;span class=&quot;nt&quot;&gt;-l&lt;/span&gt; build/app/outputs/bundle/release/app-release.aab &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  | rg &lt;span class=&quot;s1&quot;&gt;&apos;assets/dexopt/baseline\.prof&apos;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h2 id=&quot;출시-전에-확인할-것&quot;&gt;출시 전에 확인할 것&lt;/h2&gt;

&lt;p&gt;Baseline Profile은 “빌드 성공”만으로 효과가 증명되지 않는다. Android 공식 문서도 물리 기기에서 생성·벤치마크하고, Play Store 설치와 내부 테스트 트랙을 구분한다. Internal App Sharing에서는 프로파일 효과를 기대하기 어렵고, non-Play 배포는 백그라운드 dexopt 이후에야 반영될 수 있다.&lt;/p&gt;

&lt;ul class=&quot;task-list&quot;&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;Debug가 아닌 서명된 release AAB를 기준으로 측정했다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;앱 시작, 로그인 후 홈, 대표 목록 진입처럼 반복 경로를 1~3개로 좁혔다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;생성 전후를 같은 기기·같은 초기 데이터로 비교했다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;AAB에 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;assets/dexopt/baseline.prof&lt;/code&gt;가 들어갔다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;프로파일 생성 테스트가 실패해도 임의의 빈 파일을 커밋하지 않았다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;프로파일과 무관한 Flutter 네트워크·DB·이미지 로딩 병목을 별도로 측정했다.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;프로파일을 넣었는데도 첫 화면이 느리다면 Flutter 엔진 초기화, 동기식 플러그인 호출, 큰 이미지 디코딩, 첫 API 대기처럼 프로파일이 해결하지 못하는 구간일 수 있다. 반대로 측정 없이 프로파일 생성만 자동화하면 CI 시간이 늘고, 실제 사용하지 않는 경로에 최적화가 집중된다.&lt;/p&gt;

&lt;p&gt;짧게 정리하면, Flutter Android의 Baseline Profile은 Dart 성능 옵션이 아니라 Android release 산출물에 실행 경로를 추가하는 운영 설정이다. AGP·Macrobenchmark·Profile Installer 조건을 맞추고, 실제 사용 경로를 생성한 뒤, Play 내부 테스트 트랙의 release 설치본에서 전후 시간을 비교해야 출시 판단에 쓸 수 있다.&lt;/p&gt;

&lt;p&gt;참고 문서: &lt;a href=&quot;https://developer.android.com/topic/performance/baselineprofiles/overview&quot;&gt;Android Baseline Profiles 개요&lt;/a&gt;, &lt;a href=&quot;https://developer.android.com/topic/performance/baselineprofiles/create-baselineprofile&quot;&gt;Baseline Profile 생성&lt;/a&gt;, &lt;a href=&quot;https://docs.flutter.dev/testing/build-modes&quot;&gt;Flutter 빌드 모드&lt;/a&gt;&lt;/p&gt;
</description>
        <pubDate>Tue, 17 Nov 2026 00:00:00 +0900</pubDate>
        <link>https://colin-ch-flutter.github.io/2026-11-17/23-00-00-4740480-flutter-android-baseline-profile-release/</link>
        <guid isPermaLink="true">https://colin-ch-flutter.github.io/2026-11-17/23-00-00-4740480-flutter-android-baseline-profile-release/</guid>
        
        <category>Flutter</category>
        
        <category>Android</category>
        
        <category>성능최적화</category>
        
        <category>출시</category>
        
        <category>CI/CD</category>
        
        
      </item>
    
      <item>
        <title>Flutter Android 16 KB page size 오류 - 네이티브 플러그인 출시 점검</title>
        <description>&lt;p&gt;&lt;img src=&quot;https://images.unsplash.com/photo-1607252650355-f7fd0460ccdb?auto=format&amp;amp;fit=crop&amp;amp;w=1600&amp;amp;q=80&quot; alt=&quot;Flutter Android 16 KB page size 출시 점검&quot; /&gt;&lt;/p&gt;

&lt;p&gt;그림에서 볼 부분은 Flutter 코드가 아니라 Google Play에 올라가는 AAB 안의 네이티브 라이브러리다.&lt;/p&gt;

&lt;p&gt;Google Play에서 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Your app uses native libraries that don&apos;t support 16 KB memory page sizes&lt;/code&gt; 경고를 받은 Flutter 앱이라면, Dart 코드를 고치기보다 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;*.so&lt;/code&gt;를 포함한 플러그인과 Flutter SDK를 확인하는 편이 빠르다. 네이티브 코드를 전혀 포함하지 않는 순수 Dart 앱에는 이 글의 NDK 수정이 필요하지 않다. 반대로 카메라·지도·DB·ML 플러그인이 들어간 앱은 빌드가 성공해도 AAB 검사에서 막힐 수 있다.&lt;/p&gt;

&lt;h2 id=&quot;왜-flutter-앱에서-발생하나&quot;&gt;왜 Flutter 앱에서 발생하나&lt;/h2&gt;

&lt;p&gt;Android 15부터 16 KB 메모리 페이지 기기를 지원할 수 있고, Google Play는 Android 15 이상을 대상으로 하는 네이티브 코드 포함 앱에 호환성을 요구한다. Android 공식 문서 기준으로 2027년 2월 1일부터는 호환되지 않는 업데이트를 출시할 수 없다. 2026년 11월 현재 새 업데이트를 준비한다면 경고를 무시하고 미루기보다 이번 빌드에서 확인하는 편이 안전하다.&lt;/p&gt;

&lt;p&gt;Flutter 엔진 자체만의 문제라고 단정하면 안 된다. 오래된 AAR, C/C++ 플러그인, 사전 빌드된 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;arm64-v8a/*.so&lt;/code&gt;가 4 KB 정렬로 남아 있는 경우가 더 까다롭다.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;확인 대상&lt;/th&gt;
      &lt;th&gt;판단&lt;/th&gt;
      &lt;th&gt;대응&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;*.so&lt;/code&gt;가 없음&lt;/td&gt;
      &lt;td&gt;Java/Kotlin 또는 순수 Dart 중심&lt;/td&gt;
      &lt;td&gt;NDK 변경 없이 AAB만 점검&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Flutter SDK가 오래됨&lt;/td&gt;
      &lt;td&gt;엔진·기본 NDK가 오래될 수 있음&lt;/td&gt;
      &lt;td&gt;Flutter 3.38 이상으로 업그레이드 검토&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;플러그인 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.so&lt;/code&gt;만 실패&lt;/td&gt;
      &lt;td&gt;의존성의 사전 빌드 바이너리 문제&lt;/td&gt;
      &lt;td&gt;해당 플러그인 업데이트 또는 대체&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;직접 만든 JNI/NDK 코드 실패&lt;/td&gt;
      &lt;td&gt;링크 정렬과 도구체인 문제&lt;/td&gt;
      &lt;td&gt;NDK r28 이상으로 재빌드&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;우선-flutter와-ndk-조건을-맞춘다&quot;&gt;우선 Flutter와 NDK 조건을 맞춘다&lt;/h2&gt;

&lt;p&gt;Flutter 3.38은 Android 네이티브 코드의 16 KB 정렬을 위한 기본 NDK를 r28로 올렸다. 따라서 오래된 프로젝트에서 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;android/app/build.gradle&lt;/code&gt;의 NDK를 무작정 바꾸기보다 Flutter 버전, AGP, Gradle 조합을 함께 확인해야 한다.&lt;/p&gt;

&lt;p&gt;프로젝트에서 실제로 사용하는 값부터 확인하는 명령은 다음과 같다.&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;flutter &lt;span class=&quot;nt&quot;&gt;--version&lt;/span&gt;
rg &lt;span class=&quot;s2&quot;&gt;&quot;ndkVersion|compileSdk|targetSdk&quot;&lt;/span&gt; android
flutter pub outdated
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;직접 NDK를 빌드하는 플러그인이라면 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;android/app/build.gradle&lt;/code&gt; 또는 플러그인 모듈의 설정을 확인한다. NDK 버전만 올려도 소스가 재컴파일되는 프로젝트와, 저장소에 미리 빌드된 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.so&lt;/code&gt;를 계속 복사하는 프로젝트는 결과가 다르다. 후자는 패키지 제공자가 새 바이너리를 배포해야 해결된다.&lt;/p&gt;

&lt;h2 id=&quot;aab-안에서-실패한-라이브러리를-찾는다&quot;&gt;AAB 안에서 실패한 라이브러리를 찾는다&lt;/h2&gt;

&lt;p&gt;릴리스 빌드가 끝난 뒤에는 소스가 아니라 최종 산출물을 확인해야 한다. 아래처럼 AAB를 임시 디렉터리에 풀면 어떤 ABI의 라이브러리가 들어갔는지 추적할 수 있다.&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;flutter clean
flutter pub get
flutter build appbundle &lt;span class=&quot;nt&quot;&gt;--release&lt;/span&gt;

&lt;span class=&quot;nb&quot;&gt;rm&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-rf&lt;/span&gt; /tmp/flutter-aab-check
&lt;span class=&quot;nb&quot;&gt;mkdir&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-p&lt;/span&gt; /tmp/flutter-aab-check
unzip &lt;span class=&quot;nt&quot;&gt;-q&lt;/span&gt; build/app/outputs/bundle/release/app-release.aab &lt;span class=&quot;nt&quot;&gt;-d&lt;/span&gt; /tmp/flutter-aab-check
find /tmp/flutter-aab-check &lt;span class=&quot;nt&quot;&gt;-name&lt;/span&gt; &lt;span class=&quot;s1&quot;&gt;&apos;*.so&apos;&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-print&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;APK를 만들 수 있는 환경이라면 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;zipalign&lt;/code&gt;으로 패키지 정렬도 확인한다.&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;flutter build apk &lt;span class=&quot;nt&quot;&gt;--release&lt;/span&gt;
zipalign &lt;span class=&quot;nt&quot;&gt;-c&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-P&lt;/span&gt; 16 &lt;span class=&quot;nt&quot;&gt;-v&lt;/span&gt; 4 build/app/outputs/flutter-apk/app-release.apk
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;이 명령이 성공해도 모든 네이티브 코드가 16 KB에서 정상 실행된다는 뜻은 아니다. AAB의 각 ABI를 Android Studio APK Analyzer 또는 16 KB 시스템 이미지에서 확인해야 한다. 실패한 파일명이 특정 플러그인 경로를 가리키면, 앱 코드에 임시 플래그를 추가하기보다 그 플러그인의 릴리스 노트와 이슈에서 16 KB 지원 버전을 찾아야 한다.&lt;/p&gt;

&lt;h2 id=&quot;출시-전-체크리스트&quot;&gt;출시 전 체크리스트&lt;/h2&gt;

&lt;ul class=&quot;task-list&quot;&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter --version&lt;/code&gt;이 프로젝트가 의도한 안정 버전인가&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;앱과 플러그인에 사전 빌드된 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;arm64-v8a/*.so&lt;/code&gt;가 있는가&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;NDK를 올린 뒤 실제로 네이티브 모듈이 재컴파일됐는가&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;최종 AAB에서 ABI별 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.so&lt;/code&gt; 목록을 확인했는가&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;APK Analyzer 또는 16 KB 에뮬레이터에서 설치·실행했는가&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;Play Console 경고가 사라진 동일 버전의 AAB를 업로드했는가&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;무료로 해결되는 조건도 있다. 네이티브 플러그인이 사용되지 않는 앱이라면 NDK를 추가 설치하거나 패키지를 구매할 이유가 없다. 반대로 오래된 상용 SDK가 문제라면 설정 한 줄보다 SDK 교체·업데이트 비용이 더 크므로, 출시 직전에 전체 플러그인을 한꺼번에 올리지 말고 실패한 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.so&lt;/code&gt;를 기준으로 하나씩 바꾸는 편이 복구하기 쉽다.&lt;/p&gt;

&lt;p&gt;핵심은 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter build&lt;/code&gt; 성공 여부가 아니라 Google Play에 제출할 AAB 내부의 네이티브 바이너리다. Flutter 3.38과 NDK r28은 출발점일 뿐이며, 최종 판단은 플러그인 바이너리와 16 KB 환경 실행 결과로 내려야 한다.&lt;/p&gt;

&lt;p&gt;참고 기준은 &lt;a href=&quot;https://developer.android.com/guide/practices/page-sizes&quot;&gt;Android 16 KB page size 공식 문서&lt;/a&gt;, &lt;a href=&quot;https://support.google.com/googleplay/android-developer/answer/17492799&quot;&gt;Google Play 기술 품질 요구사항&lt;/a&gt;, &lt;a href=&quot;https://flutter.dev/blog/whats-new-in-flutter-3-38&quot;&gt;Flutter 3.38 변경 사항&lt;/a&gt;이다.&lt;/p&gt;
</description>
        <pubDate>Mon, 16 Nov 2026 00:00:00 +0900</pubDate>
        <link>https://colin-ch-flutter.github.io/2026-11-16/23-00-00-4728135-flutter-android-16kb-page-size-release/</link>
        <guid isPermaLink="true">https://colin-ch-flutter.github.io/2026-11-16/23-00-00-4728135-flutter-android-16kb-page-size-release/</guid>
        
        <category>Flutter</category>
        
        <category>Android</category>
        
        <category>배포·운영</category>
        
        <category>성능최적화</category>
        
        <category>CI/CD</category>
        
        
      </item>
    
      <item>
        <title>Flutter Android 15·16 edge-to-edge 오류 - 출시 후 상태바와 하단 버튼이 겹칠 때</title>
        <description>&lt;p&gt;&lt;img src=&quot;https://images.unsplash.com/photo-1551650975-87deedd944c3?w=1200&amp;amp;q=80&quot; alt=&quot;Flutter Android 15 edge-to-edge 출시 레이아웃 점검&quot; /&gt;&lt;/p&gt;

&lt;p&gt;Flutter 앱을 Android 15·16에 출시한 뒤 상태바 아래로 제목이 들어가거나 하단 버튼이 내비게이션 바에 가려진다면, target SDK를 다시 낮추기보다 edge-to-edge를 기준으로 화면 inset을 정리하는 편이 맞다. 단순 화면이라면 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SafeArea&lt;/code&gt;로 해결할 수 있지만, 이미 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MediaQuery.padding&lt;/code&gt;을 더하는 공통 레이아웃이 있다면 이중 여백이 생긴다.&lt;/p&gt;

&lt;h2 id=&quot;왜-갑자기-겹치는가&quot;&gt;왜 갑자기 겹치는가&lt;/h2&gt;

&lt;p&gt;Android 문서 기준으로 target SDK 35 이상인 앱은 Android 15 이상에서 화면 전체에 그려진다. 상태바와 내비게이션 바가 차지하던 영역까지 Flutter 캔버스가 사용하므로, 예전처럼 화면 높이를 안전 영역으로 가정한 레이아웃이 그대로 노출된다.&lt;/p&gt;

&lt;p&gt;Flutter 공식 문서도 Flutter 3.27부터 기본 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter.targetSdkVersion&lt;/code&gt;이 Android 15를 대상으로 하면서 이 변화가 시작된다고 설명한다. Android 16에서는 edge-to-edge를 끄는 기존 우회책을 사용할 때 앱이 충돌할 수 있으므로, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;windowOptOutEdgeToEdgeEnforcement&lt;/code&gt;를 영구 해법처럼 넣으면 안 된다.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;증상&lt;/th&gt;
      &lt;th&gt;실제 원인&lt;/th&gt;
      &lt;th&gt;확인 지점&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;제목이 상태바와 겹침&lt;/td&gt;
      &lt;td&gt;상단 inset 미반영&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Scaffold&lt;/code&gt; 안의 공통 AppBar&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;FAB·하단 버튼이 가려짐&lt;/td&gt;
      &lt;td&gt;하단 system bar inset 미반영&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bottomNavigationBar&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Stack&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;화면마다 여백이 두 배&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SafeArea&lt;/code&gt;와 수동 padding 중복&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MediaQuery.paddingOf(context)&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Android 16에서 실행 문제&lt;/td&gt;
      &lt;td&gt;Android 15용 opt-out 스타일 유지&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;values/&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;values-night/&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;values-35/&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;flutter-화면은-안전-영역의-책임을-한-곳에-둔다&quot;&gt;Flutter 화면은 안전 영역의 책임을 한 곳에 둔다&lt;/h2&gt;

&lt;p&gt;화면 전체를 감싸는지, 특정 조작 요소만 감싸는지를 정해야 한다. 아래처럼 화면 전체를 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SafeArea&lt;/code&gt;로 감싸면 일반적인 폼과 목록은 빠르게 안정화할 수 있다.&lt;/p&gt;

&lt;div class=&quot;language-dart highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kd&quot;&gt;class&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;SettingsPage&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;extends&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;StatelessWidget&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;SettingsPage&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;({&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;super&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;});&lt;/span&gt;

  &lt;span class=&quot;nd&quot;&gt;@override&lt;/span&gt;
  &lt;span class=&quot;n&quot;&gt;Widget&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;build&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;BuildContext&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;context&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Scaffold&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
      &lt;span class=&quot;nl&quot;&gt;body:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;SafeArea&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;nl&quot;&gt;child:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ListView&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
          &lt;span class=&quot;nl&quot;&gt;padding:&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;EdgeInsets&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;all&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;16&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
          &lt;span class=&quot;nl&quot;&gt;children:&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;Text&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;설정&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;SizedBox&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;height:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;24&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
            &lt;span class=&quot;c1&quot;&gt;// 설정 항목&lt;/span&gt;
          &lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
      &lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;다만 배경 이미지는 상태바 뒤까지 펼치고 버튼만 피해야 한다면 전체 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SafeArea&lt;/code&gt;는 적절하지 않다. 이때는 버튼 영역에만 하단 여백을 적용한다. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SafeArea&lt;/code&gt;와 아래 코드를 같은 위젯 계층에 함께 넣지 않는 것이 핵심이다.&lt;/p&gt;

&lt;div class=&quot;language-dart highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kd&quot;&gt;final&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;bottomInset&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;MediaQuery&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;paddingOf&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;context&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;bottom&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;Positioned&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
  &lt;span class=&quot;nl&quot;&gt;left:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;16&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;nl&quot;&gt;right:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;16&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;nl&quot;&gt;bottom:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;bottomInset&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;16&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;nl&quot;&gt;child:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;FilledButton&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;nl&quot;&gt;onPressed:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;onSubmit&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;nl&quot;&gt;child:&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Text&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;저장&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Scaffold&lt;/code&gt;의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bottomNavigationBar&lt;/code&gt;를 사용하는 경우에는 공통 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AppShell&lt;/code&gt;에서 이미 inset을 처리하는지 확인한다. 페이지마다 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SafeArea&lt;/code&gt;를 추가하면 기기와 내비게이션 방식에 따라 하단 간격이 2번 더해질 수 있다.&lt;/p&gt;

&lt;h2 id=&quot;출시-전-점검-순서&quot;&gt;출시 전 점검 순서&lt;/h2&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;android/app/build.gradle&lt;/code&gt; 또는 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.kts&lt;/code&gt;에서 실제 release variant의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;targetSdk&lt;/code&gt;를 확인한다. Flutter 변수에 의존하면 Flutter 버전 변경으로 값이 달라질 수 있다.&lt;/li&gt;
  &lt;li&gt;Android 15/API 35와 Android 16/API 36 에뮬레이터에서 제스처 내비게이션, 3버튼 내비게이션을 각각 확인한다.&lt;/li&gt;
  &lt;li&gt;세로뿐 아니라 가로 방향에서 display cutout과 하단 버튼을 확인한다.&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SafeArea&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MediaQuery.padding&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;viewPadding&lt;/code&gt;이 한 화면에서 중복 사용되는지 검색한다.&lt;/li&gt;
  &lt;li&gt;release APK 또는 AAB로 확인한다. debug에서만 보이는 시스템 바 설정을 기준으로 판단하지 않는다.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Android 15에 한해 출시를 잠시 미뤄야 한다면 Flutter 문서의 임시 opt-out 스타일을 사용할 수 있다. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;values/styles.xml&lt;/code&gt;과 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;values-night/styles.xml&lt;/code&gt;에 아래 항목을 넣되, Android 16 이상을 위해 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;values-35&lt;/code&gt;에서는 이 항목이 없는 스타일을 제공해야 한다.&lt;/p&gt;

&lt;div class=&quot;language-xml highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nt&quot;&gt;&amp;lt;item&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;name=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;android:windowOptOutEdgeToEdgeEnforcement&quot;&lt;/span&gt;&lt;span class=&quot;nt&quot;&gt;&amp;gt;&lt;/span&gt;true&lt;span class=&quot;nt&quot;&gt;&amp;lt;/item&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;이 설정은 화면 코드를 고친 것이 아니다. Android 16까지 지원하는 앱이라면 배포 전에 제거하고 inset 기반 레이아웃으로 전환하는 것이 안전하다. 특히 광고 배너, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Stack&lt;/code&gt; 위의 고정 버튼, 커스텀 바텀시트는 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SafeArea&lt;/code&gt; 하나만으로 시각적 겹침과 터치 영역을 모두 해결하지 못할 수 있다.&lt;/p&gt;

&lt;h2 id=&quot;짧은-요점-정리&quot;&gt;짧은 요점 정리&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;target SDK 35 이상과 Android 15 이상 조합에서는 edge-to-edge가 기본이다.&lt;/li&gt;
  &lt;li&gt;전체 화면은 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SafeArea&lt;/code&gt;, 특정 조작 요소는 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MediaQuery.paddingOf&lt;/code&gt; 중 하나로 책임을 정한다.&lt;/li&gt;
  &lt;li&gt;Flutter 3.27 이후 target SDK 기본값 변화도 함께 확인한다.&lt;/li&gt;
  &lt;li&gt;Android 15 opt-out 스타일은 임시 대응이며 Android 16 출시 전략으로 남겨두지 않는다.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;근거: &lt;a href=&quot;https://docs.flutter.dev/release/breaking-changes/default-systemuimode-edge-to-edge&quot;&gt;Flutter edge-to-edge 변경 안내&lt;/a&gt;, &lt;a href=&quot;https://developer.android.com/develop/ui/views/layout/edge-to-edge&quot;&gt;Android edge-to-edge 공식 문서&lt;/a&gt; (2026-11-16 확인).&lt;/p&gt;
</description>
        <pubDate>Mon, 16 Nov 2026 00:00:00 +0900</pubDate>
        <link>https://colin-ch-flutter.github.io/2026-11-16/23-00-00-4715790-flutter-android-edge-to-edge-release/</link>
        <guid isPermaLink="true">https://colin-ch-flutter.github.io/2026-11-16/23-00-00-4715790-flutter-android-edge-to-edge-release/</guid>
        
        <category>Flutter</category>
        
        <category>Android</category>
        
        <category>배포·운영</category>
        
        <category>UI</category>
        
        <category>성능최적화</category>
        
        
      </item>
    
      <item>
        <title>Flutter 3.50 Android 빌드 오류 - AGP 9.1.1과 Gradle 9.5.0 맞추기</title>
        <description>&lt;p&gt;&lt;img src=&quot;https://images.unsplash.com/photo-1555066931-4365d14bab8c?auto=format&amp;amp;fit=crop&amp;amp;w=1600&amp;amp;q=80&quot; alt=&quot;Flutter 3.50 Android Gradle 빌드 도구 점검&quot; /&gt;&lt;/p&gt;

&lt;p&gt;이 그림에서 봐야 할 부분은 Dart 코드가 아니라 Flutter·AGP·Gradle·Java가 한 줄의 출시 경로로 묶인다는 점이다.&lt;/p&gt;

&lt;p&gt;Flutter 3.50으로 올린 뒤 Android release 빌드가 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Your project&apos;s Android Gradle Plugin version ... is lower than ... 9.1.1&lt;/code&gt;에서 멈춘다면 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter clean&lt;/code&gt;을 반복할 문제가 아니다. 기존 프로젝트의 AGP를 최소 9.1.1로 올리고 Gradle과 Java도 함께 맞추는 선택이 정석이다. 당장 CI를 복구해야 할 때는 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--android-skip-build-dependency-validation&lt;/code&gt;으로 검사를 건너뛸 수 있지만, 출시 기준으로 남기면 안 된다. Android 빌드가 없거나 Flutter 3.47 이하로 고정된 프로젝트에는 이 오류가 바로 생기지 않는다.&lt;/p&gt;

&lt;h2 id=&quot;왜-갑자기-ci에서만-멈추는가&quot;&gt;왜 갑자기 CI에서만 멈추는가&lt;/h2&gt;

&lt;p&gt;Flutter 3.50은 2026년 11월 11일 stable로 나왔고, 새 Android 프로젝트는 AGP 9.3.1, Gradle 9.5.0, Java 17 조합을 사용한다. 반면 오래된 프로젝트나 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;channel: stable&lt;/code&gt;만 지정한 CI는 서로 다른 SDK를 사용할 수 있다. 내 컴퓨터는 3.47인데 CI가 먼저 3.50을 받은 상황이면 코드 변경 없이도 Gradle 플러그인 적용 단계에서 실패한다.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;확인 대상&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;출시 기준으로 볼 값&lt;/th&gt;
      &lt;th&gt;놓치기 쉬운 지점&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Flutter&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;3.50.0&lt;/td&gt;
      &lt;td&gt;로컬과 CI 버전이 다름&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Android Gradle Plugin&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;9.1.1 이상&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;settings.gradle(.kts)&lt;/code&gt; 또는 오래된 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;build.gradle&lt;/code&gt;에 분산됨&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Gradle wrapper&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;9.5.0 권장&lt;/td&gt;
      &lt;td&gt;AGP만 올리면 wrapper가 낮을 수 있음&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Java&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;17 이상&lt;/td&gt;
      &lt;td&gt;Android Studio 내장 JDK와 CI &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;JAVA_HOME&lt;/code&gt;이 다름&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Flutter 공식 발표의 새 프로젝트 기본값은 AGP 9.3.1과 Gradle 9.5.0이다. Android Studio 공식 표에서도 API 37에 필요한 최소 AGP는 9.1.1로 안내한다. 따라서 9.1.1은 급한 기존 프로젝트를 살리는 최소선이고, 새 프로젝트 설정을 그대로 맞출 수 있다면 9.3.1 조합을 검토하면 된다.&lt;/p&gt;

&lt;h2 id=&quot;먼저-실제-버전을-출력한다&quot;&gt;먼저 실제 버전을 출력한다&lt;/h2&gt;

&lt;p&gt;수정 전에 로컬과 CI에서 같은 명령을 실행해 버전 차이를 기록해야 한다.&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;flutter &lt;span class=&quot;nt&quot;&gt;--version&lt;/span&gt;
java &lt;span class=&quot;nt&quot;&gt;-version&lt;/span&gt;
./gradlew &lt;span class=&quot;nt&quot;&gt;--version&lt;/span&gt;
rg &lt;span class=&quot;s1&quot;&gt;&apos;com.android.application|com.android.tools.build:gradle&apos;&lt;/span&gt; android
rg &lt;span class=&quot;s1&quot;&gt;&apos;distributionUrl&apos;&lt;/span&gt; android/gradle/wrapper/gradle-wrapper.properties
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;최근 템플릿은 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;android/settings.gradle.kts&lt;/code&gt;의 plugins 블록에 버전이 있다.&lt;/p&gt;

&lt;div class=&quot;language-kotlin highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nf&quot;&gt;plugins&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;nf&quot;&gt;id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;com.android.application&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;version&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;9.1.1&quot;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;apply&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;false&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;오래된 프로젝트라면 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;android/build.gradle&lt;/code&gt;의 classpath를 바꿔야 한다.&lt;/p&gt;

&lt;div class=&quot;language-groovy highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;dependencies&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;classpath&lt;/span&gt; &lt;span class=&quot;s1&quot;&gt;&apos;com.android.tools.build:gradle:9.1.1&apos;&lt;/span&gt;
&lt;span class=&quot;o&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;AGP를 9.1.1로 올렸는데 wrapper가 9.3.1보다 낮다면 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;android/gradle/wrapper/gradle-wrapper.properties&lt;/code&gt;의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;distributionUrl&lt;/code&gt;도 확인한다. Flutter 3.50 새 프로젝트와 같은 기준을 택한다면 Gradle 9.5.0과 Java 17을 함께 사용한다. 플러그인 중 AGP 9의 built-in Kotlin을 아직 지원하지 않는 것이 있으면 전체 업그레이드 전에 해당 플러그인의 호환 버전을 확인해야 한다.&lt;/p&gt;

&lt;h2 id=&quot;오늘-출시해야-할-때의-우회&quot;&gt;오늘 출시해야 할 때의 우회&lt;/h2&gt;

&lt;p&gt;검사만 통과시키는 임시 명령은 다음과 같다.&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;flutter build appbundle &lt;span class=&quot;nt&quot;&gt;--release&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--android-skip-build-dependency-validation&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;이 옵션은 AGP 버전을 올려 주지 않고 Flutter의 사전 검증만 끈다. 그래서 AAB가 만들어져도 plugin API, Gradle task, R8, 서명 단계가 안전하다는 뜻은 아니다. 내부 테스트 트랙에 올려 설치·실행·로그인·네이티브 플러그인 호출까지 확인하는 동안에만 사용한다. CI가 갑자기 깨진 날에는 Flutter 버전을 3.47.x처럼 고정해 배포를 잠시 멈추지 않게 할 수 있지만, 고정은 업그레이드를 미루는 방법이지 해결은 아니다.&lt;/p&gt;

&lt;h2 id=&quot;출시-전-체크리스트&quot;&gt;출시 전 체크리스트&lt;/h2&gt;

&lt;ul class=&quot;task-list&quot;&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;로컬과 CI의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter --version&lt;/code&gt;, Java, Gradle 출력이 기록돼 있다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;AGP가 9.1.1 이상이고, 설정 파일에 오래된 AGP 선언이 하나 더 남아 있지 않다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;Gradle wrapper와 Java 17 조합으로 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter build appbundle --release&lt;/code&gt;를 실행했다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;AGP 9를 지원하지 않는 Flutter 플러그인을 찾아 업데이트 또는 교체 판단을 했다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;우회 플래그 없이 내부 테스트 트랙 설치본을 실행했다.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;핵심은 Flutter 3.50 오류를 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;clean&lt;/code&gt; 명령으로 지우는 것이 아니라 빌드 도구의 최소선과 새 프로젝트 기준을 구분하는 데 있다. 오늘 배포를 위해 검사를 건너뛸 수는 있지만, 다음 빌드에서 같은 오류가 재발하지 않게 하려면 AGP 9.1.1 이상·Gradle 9.5.0·Java 17을 CI에 명시하고 플러그인 호환성까지 확인해야 한다.&lt;/p&gt;

&lt;p&gt;참고 문서: &lt;a href=&quot;https://flutter.dev/blog/whats-new-in-flutter-3-50&quot;&gt;Flutter 3.50 변경 사항&lt;/a&gt;, &lt;a href=&quot;https://developer.android.com/studio/releases&quot;&gt;Android Studio와 AGP 호환표&lt;/a&gt;, &lt;a href=&quot;https://github.com/flutter/flutter/blob/master/docs/platforms/android/Resolving-common-build-failures.md&quot;&gt;Flutter Android 빌드 실패 해결 안내&lt;/a&gt;&lt;/p&gt;
</description>
        <pubDate>Sun, 15 Nov 2026 00:00:00 +0900</pubDate>
        <link>https://colin-ch-flutter.github.io/2026-11-15/23-00-00-4691100-flutter-350-android-agp-911-build/</link>
        <guid isPermaLink="true">https://colin-ch-flutter.github.io/2026-11-15/23-00-00-4691100-flutter-350-android-agp-911-build/</guid>
        
        <category>Flutter</category>
        
        <category>Android</category>
        
        <category>CI/CD</category>
        
        <category>배포</category>
        
        <category>성능최적화</category>
        
        
      </item>
    
      <item>
        <title>Flutter Web CSP 오류 - release에서 flutter_bootstrap.js와 WASM이 차단될 때</title>
        <description>&lt;p&gt;&lt;img src=&quot;https://images.unsplash.com/photo-1551288049-bebda4e38f71?auto=format&amp;amp;fit=crop&amp;amp;w=1600&amp;amp;q=80&quot; alt=&quot;Flutter Web release의 CSP와 WASM 로딩을 점검하는 브라우저 개발자 도구 화면&quot; /&gt;&lt;/p&gt;

&lt;p&gt;이 그림에서 볼 것은 release 시작 직전 브라우저 콘솔의 차단 리소스다.&lt;/p&gt;

&lt;p&gt;Flutter Web을 CSP(Content-Security-Policy)와 함께 운영한다면 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter_bootstrap.js&lt;/code&gt; 차단과 WASM 컴파일 차단을 따로 고쳐야 한다. 외부 부트스트랩만 쓰는 앱은 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;script-src &apos;self&apos;&lt;/code&gt;와 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&apos;wasm-unsafe-eval&apos;&lt;/code&gt;부터 확인하면 되고, ``를 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;index.html&lt;/code&gt;에 인라인한 앱은 요청마다 바뀌는 nonce를 연결해야 한다. 보안 정책을 빠르게 통과시키려고 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&apos;unsafe-eval&apos;&lt;/code&gt;과 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&apos;unsafe-inline&apos;&lt;/code&gt;을 무조건 넣는 방식은 이 글의 대상이 아니다.&lt;/p&gt;

&lt;h2 id=&quot;오류가-release에서만-보이는-이유&quot;&gt;오류가 release에서만 보이는 이유&lt;/h2&gt;

&lt;p&gt;개발 서버에서는 실행되지만 배포 서버에서 아래 오류가 난다.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;콘솔 메시지&lt;/th&gt;
      &lt;th&gt;원인&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter_bootstrap.js&lt;/code&gt; 차단&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;script-src&lt;/code&gt;에 현재 origin 없음&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;inline script 차단&lt;/td&gt;
      &lt;td&gt;bootstrap에 nonce·hash 없음&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;WebAssembly.compileStreaming&lt;/code&gt; 차단&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&apos;wasm-unsafe-eval&apos;&lt;/code&gt; 없음&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;엔진 style 차단&lt;/td&gt;
      &lt;td&gt;loader에 nonce 미전달&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Flutter 공식 초기화 기준으로 커스텀 bootstrap에는 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;,&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_flutter.loader.load()&lt;/code&gt;가 필요하다.&lt;/p&gt;

&lt;h2 id=&quot;외부-bootstrap과-인라인-bootstrap-구분&quot;&gt;외부 bootstrap과 인라인 bootstrap 구분&lt;/h2&gt;

&lt;p&gt;HTML마다 nonce를 넣기 어려운 정적 호스팅은 외부 script 방식을 쓴다.&lt;/p&gt;

&lt;div class=&quot;language-http highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;err&quot;&gt;Content-Security-Policy: default-src &apos;self&apos;; script-src &apos;self&apos; &apos;wasm-unsafe-eval&apos;; style-src &apos;self&apos;; connect-src &apos;self&apos; https: wss:; object-src &apos;none&apos;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;API·CDN 주소는 실제 사용하는 호스트만 남긴다. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&apos;wasm-unsafe-eval&apos;&lt;/code&gt;은 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&apos;unsafe-eval&apos;&lt;/code&gt;보다 범위가 좁다.&lt;/p&gt;

&lt;p&gt;인라인 ``가 필요하면 서버가 요청마다 nonce를 만들고 CSP, HTML, Flutter loader에 같은 값을 전달한다.&lt;/p&gt;

&lt;div class=&quot;language-html highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nt&quot;&gt;&amp;lt;meta&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;name=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;flutter-csp-nonce&quot;&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;content=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;nt&quot;&gt;&amp;gt;&lt;/span&gt;
&lt;span class=&quot;nt&quot;&gt;&amp;lt;script &lt;/span&gt;&lt;span class=&quot;na&quot;&gt;nonce=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;nt&quot;&gt;&amp;gt;&lt;/span&gt;
  
  
  &lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;nonce&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;document&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;querySelector&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;meta[name=&quot;flutter-csp-nonce&quot;]&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;).&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;content&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;_flutter&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;loader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;load&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;({&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;nonce&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;});&lt;/span&gt;
&lt;span class=&quot;nt&quot;&gt;&amp;lt;/script&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;고정 nonce는 재사용하지 않는다. ``를 빼거나 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;main.dart.js&lt;/code&gt;를 하드코딩하면 해시 빌드에서 entrypoint를 찾지 못한다.&lt;/p&gt;

&lt;h2 id=&quot;배포-직전-체크리스트&quot;&gt;배포 직전 체크리스트&lt;/h2&gt;

&lt;ul class=&quot;task-list&quot;&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter build web --wasm&lt;/code&gt; 뒤 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter_bootstrap.js&lt;/code&gt;가 200이다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;HTML nonce, CSP nonce, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;config.nonce&lt;/code&gt;가 요청마다 일치한다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;WASM 대상 브라우저에 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&apos;wasm-unsafe-eval&apos;&lt;/code&gt;이 허용된다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;connect-src&lt;/code&gt;에 API·WebSocket 주소가 있다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;release 콘솔에서 최초 차단 리소스를 확인했다.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;외부·인라인 bootstrap의 조건을 나누고, WASM에는 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&apos;wasm-unsafe-eval&apos;&lt;/code&gt;, 인라인 요소에는 요청 단위 nonce를 적용하면 된다. nonce 주입이 어려우면 인라인을 제거한다.&lt;/p&gt;

&lt;p&gt;공식 기준은 &lt;a href=&quot;https://docs.flutter.dev/platform-integration/web/initialization&quot;&gt;Flutter Web 앱 초기화 문서&lt;/a&gt;, &lt;a href=&quot;https://docs.flutter.dev/platform-integration/web/wasm&quot;&gt;Flutter WebAssembly 문서&lt;/a&gt;, &lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy&quot;&gt;MDN CSP 헤더 문서&lt;/a&gt;다.&lt;/p&gt;
</description>
        <pubDate>Sun, 15 Nov 2026 00:00:00 +0900</pubDate>
        <link>https://colin-ch-flutter.github.io/2026-11-15/22-00-00-4678755-flutter-web-csp-wasm-release/</link>
        <guid isPermaLink="true">https://colin-ch-flutter.github.io/2026-11-15/22-00-00-4678755-flutter-web-csp-wasm-release/</guid>
        
        <category>Flutter</category>
        
        <category>Web</category>
        
        <category>WASM</category>
        
        <category>CI/CD</category>
        
        <category>출시</category>
        
        
      </item>
    
      <item>
        <title>Flutter iOS SwiftPM Archive 오류 - 플러그인 번들에 프로비저닝 프로파일이 전파될 때</title>
        <description>&lt;p&gt;&lt;img src=&quot;https://images.unsplash.com/photo-1512941937669-90a1b58e7e9c?auto=format&amp;amp;fit=crop&amp;amp;w=1600&amp;amp;q=80&quot; alt=&quot;Flutter iOS Swift Package Manager Archive 서명 오류를 점검하는 Xcode 화면&quot; /&gt;&lt;/p&gt;

&lt;p&gt;Flutter 3.44 이상에서 iOS Swift Package Manager(SwiftPM)를 쓰고, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter run&lt;/code&gt;은 되는데 Archive에서 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;does not support provisioning profiles&lt;/code&gt;가 나온다면 프로파일을 플러그인 번들까지 전달하는 설정을 먼저 걷어내야 한다. 앱을 수동 서명해야 하는 경우에도 프로파일의 적용 대상은 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Runner&lt;/code&gt;와 앱 확장으로 한정한다. SwiftPM을 쓰지 않거나 자동 서명을 쓰는 프로젝트에는 이 오류의 해결책을 그대로 적용할 필요가 없다.&lt;/p&gt;

&lt;h2 id=&quot;왜-플러그인-번들이-프로파일을-요구하는가&quot;&gt;왜 플러그인 번들이 프로파일을 요구하는가&lt;/h2&gt;

&lt;p&gt;Flutter 3.44부터 SwiftPM이 iOS·macOS 의존성 관리의 기본 경로가 됐다. 리소스를 포함한 플러그인은 코드 타깃과 별도의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.bundle&lt;/code&gt; 타깃으로 Archive에 나타날 수 있다. 이 번들은 앱처럼 프로비저닝 프로파일을 발급받는 대상이 아니다.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;로그의 단서&lt;/th&gt;
      &lt;th&gt;실제 대상&lt;/th&gt;
      &lt;th&gt;판단&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Runner&lt;/code&gt;가 프로파일을 찾지 못함&lt;/td&gt;
      &lt;td&gt;앱 타깃&lt;/td&gt;
      &lt;td&gt;Bundle ID·팀·인증서 확인&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;url_launcher_ios_url_launcher_ios&lt;/code&gt; 등&lt;/td&gt;
      &lt;td&gt;SwiftPM 플러그인 타깃&lt;/td&gt;
      &lt;td&gt;전역 수동 서명 설정 제거&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.../Flutter/ephemeral/Packages/.packages/&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Flutter가 생성한 패키지 사본&lt;/td&gt;
      &lt;td&gt;생성 파일을 직접 수정하지 않음&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;특히 오래된 CI 명령의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PROVISIONING_PROFILE_SPECIFIER=...&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CODE_SIGN_IDENTITY=...&lt;/code&gt; 또는 Release용 공통 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.xcconfig&lt;/code&gt;가 모든 빌드 타깃에 적용되면 이 현상이 나타난다. CocoaPods의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;post_install&lt;/code&gt;에서 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CODE_SIGNING_ALLOWED = NO&lt;/code&gt;를 넣어 우연히 통과하던 프로젝트가 SwiftPM 전환 뒤 깨지는 경우도 같은 계열이다.&lt;/p&gt;

&lt;h2 id=&quot;수정-순서&quot;&gt;수정 순서&lt;/h2&gt;

&lt;p&gt;오류 경로가 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Runner&lt;/code&gt;가 아니라 플러그인 타깃인지 확인한 뒤, 저장소에서 전역 서명 값을 찾는다.&lt;/p&gt;

&lt;div class=&quot;language-sh highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;rg &lt;span class=&quot;nt&quot;&gt;-n&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;PROVISIONING_PROFILE|CODE_SIGN_IDENTITY|CODE_SIGN_STYLE|DEVELOPMENT_TEAM&quot;&lt;/span&gt; ios .github fastlane
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;공통 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Release.xcconfig&lt;/code&gt;나 CI의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;xcodebuild&lt;/code&gt; 인자에 프로파일을 넣었다면 삭제하고, Xcode의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Runner&lt;/code&gt; 타깃 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Signing &amp;amp; Capabilities&lt;/code&gt;에서만 팀과 배포 프로파일을 지정한다. 자동 서명을 허용할 수 있는 CI라면 Runner에 유효한 팀을 설정하고 Archive 단계에서 프로파일을 강제하지 않는 편이 단순하다.&lt;/p&gt;

&lt;div class=&quot;language-sh highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;# 프로파일 이름을 모든 SwiftPM 타깃에 주입하지 않는 Archive 예시&lt;/span&gt;
flutter clean
flutter pub get
flutter build ipa &lt;span class=&quot;nt&quot;&gt;--release&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;수동 서명이 꼭 필요하다면 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;-xcconfig&lt;/code&gt;에 프로파일 값을 넣은 뒤 전체 워크스페이스에 전달하지 말고, Xcode 프로젝트의 Runner 타깃 설정으로 이동한다. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ios/Flutter/ephemeral&lt;/code&gt; 아래의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Package.swift&lt;/code&gt;나 생성된 패키지 프로젝트를 고쳐도 다음 빌드에서 다시 생성되므로 복구책이 아니다. SwiftPM을 지원하지 않는 플러그인이 섞였다면 SwiftPM을 끄는 것보다 해당 플러그인의 지원 버전과 CocoaPods fallback 조건을 별도로 확인한다.&lt;/p&gt;

&lt;h2 id=&quot;archive-전에-확인할-체크리스트&quot;&gt;Archive 전에 확인할 체크리스트&lt;/h2&gt;

&lt;ul class=&quot;task-list&quot;&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;오류 대상이 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Runner&lt;/code&gt;인지 SwiftPM 플러그인·리소스 번들인지 분리했다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Release.xcconfig&lt;/code&gt;, Fastlane, CI 환경 변수에 전역 프로파일 값이 남아 있지 않다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;Bundle ID와 프로파일은 앱 타깃에만 연결돼 있다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter clean&lt;/code&gt; 뒤 실제 Archive를 새로 만들었다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Payload/*.app/Frameworks&lt;/code&gt;와 플러그인 리소스가 포함된 최종 아카이브를 확인했다.&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;시뮬레이터 빌드 성공이 아니라 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter build ipa --release&lt;/code&gt; 결과를 출시 기준으로 삼았다.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;이 문제에서 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Set the provisioning profile value to Automatic&lt;/code&gt;이라는 Xcode의 문구를 플러그인 패키지 타깃에 그대로 적용할 수는 없다. 패키지 타깃은 앱 프로젝트에서 직접 관리하는 일반 타깃이 아니기 때문이다. 해결의 핵심은 프로파일을 더 추가하는 것이 아니라, 서명 책임을 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Runner&lt;/code&gt;로 좁히는 데 있다. Flutter의 SwiftPM 기본 전환과 프로젝트별 비활성화 옵션은 &lt;a href=&quot;https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers&quot;&gt;Swift Package Manager for app developers&lt;/a&gt;, 배포 명령은 &lt;a href=&quot;https://docs.flutter.dev/deployment/ios&quot;&gt;Flutter iOS 배포 문서&lt;/a&gt;에서 확인할 수 있다.&lt;/p&gt;
</description>
        <pubDate>Sat, 14 Nov 2026 00:00:00 +0900</pubDate>
        <link>https://colin-ch-flutter.github.io/2026-11-14/23-00-00-4654065-flutter-ios-spm-provisioning-profile/</link>
        <guid isPermaLink="true">https://colin-ch-flutter.github.io/2026-11-14/23-00-00-4654065-flutter-ios-spm-provisioning-profile/</guid>
        
        <category>Flutter</category>
        
        <category>iOS</category>
        
        <category>CI/CD</category>
        
        <category>배포</category>
        
        <category>SwiftPM</category>
        
        
      </item>
    
      <item>
        <title>Flutter 3.50 WidgetSpan RTL 오류 - 뒤집힌 인라인 위젯과 golden 테스트 고치기</title>
        <description>&lt;p&gt;&lt;img src=&quot;https://images.unsplash.com/photo-1551650975-87deedd944c3?auto=format&amp;amp;fit=crop&amp;amp;w=1600&amp;amp;q=80&quot; alt=&quot;Flutter 3.50 RTL WidgetSpan 레이아웃과 golden 테스트 점검&quot; /&gt;&lt;/p&gt;

&lt;p&gt;Flutter 3.50으로 올린 뒤 아랍어·히브리어 화면의 배지, 아이콘, 링크가 반대 위치로 이동했다면 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;WidgetSpan&lt;/code&gt;을 다시 뒤집을 문제가 아니다. 기존에 RTL 순서를 보정하던 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Transform.translate&lt;/code&gt;, span 배열 역순 처리, placeholder 좌표 반전 코드를 제거하고 논리적인 읽기 순서로 되돌리는 선택이 맞다. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;WidgetSpan&lt;/code&gt;을 쓰지 않거나 RTL 보정 코드를 넣은 적이 없는 앱은 이 변경으로 수정할 필요가 없다.&lt;/p&gt;

&lt;h2 id=&quot;문제가-생기는-조건&quot;&gt;문제가 생기는 조건&lt;/h2&gt;

&lt;p&gt;Flutter 3.50부터 텍스트 안의 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;WidgetSpan&lt;/code&gt; 위치가 소스 순서가 아니라 Unicode 양방향 알고리즘의 시각 순서를 따른다. 이전 엔진은 아랍어 문장 안에서도 placeholder를 Dart 코드에 적은 순서로 배치했다. 그래서 개발자가 위젯을 역순으로 넣거나 x 좌표를 수동으로 옮겨 화면을 맞추는 경우가 있었다.&lt;/p&gt;

&lt;p&gt;이제 엔진이 올바른 위치를 계산한다. 예전 우회 코드를 그대로 두면 보정이 두 번 적용되어 아이콘이 다시 반대쪽으로 간다.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;코드 상태&lt;/th&gt;
      &lt;th&gt;Flutter 3.49 이하&lt;/th&gt;
      &lt;th&gt;Flutter 3.50&lt;/th&gt;
      &lt;th&gt;조치&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;WidgetSpan만 사용&lt;/td&gt;
      &lt;td&gt;잘못된 RTL 위치 가능&lt;/td&gt;
      &lt;td&gt;시각 순서로 배치&lt;/td&gt;
      &lt;td&gt;코드 유지&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;span 배열을 역순으로 생성&lt;/td&gt;
      &lt;td&gt;임시로 화면 보정&lt;/td&gt;
      &lt;td&gt;순서가 다시 뒤집힘&lt;/td&gt;
      &lt;td&gt;논리 순서로 복원&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Transform으로 x 좌표 보정&lt;/td&gt;
      &lt;td&gt;임시 위치 보정&lt;/td&gt;
      &lt;td&gt;이중 보정&lt;/td&gt;
      &lt;td&gt;Transform 제거&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;golden이 기존 화면 캡처&lt;/td&gt;
      &lt;td&gt;기존 결과 통과&lt;/td&gt;
      &lt;td&gt;새 위치에서 실패&lt;/td&gt;
      &lt;td&gt;RTL golden 갱신&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;보정-코드를-논리-순서로-바꾸기&quot;&gt;보정 코드를 논리 순서로 바꾸기&lt;/h2&gt;

&lt;p&gt;인라인 아이콘 두 개를 아랍어 문장에 넣는 예시다. 실제 프로젝트에서는 문자열을 하드코딩하지 말고 번역 리소스와 span 조합을 같은 규칙으로 관리한다.&lt;/p&gt;

&lt;div class=&quot;language-dart highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;Text&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;rich&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
  &lt;span class=&quot;n&quot;&gt;TextSpan&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;nl&quot;&gt;text:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos;حالة الجهاز &apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;nl&quot;&gt;children:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;
      &lt;span class=&quot;n&quot;&gt;WidgetSpan&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;nl&quot;&gt;alignment:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;PlaceholderAlignment&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;middle&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;nl&quot;&gt;child:&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Icon&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Icons&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;wifi&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nl&quot;&gt;size:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;16&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
      &lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
      &lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;TextSpan&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;text:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos; متصل &apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
      &lt;span class=&quot;n&quot;&gt;WidgetSpan&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;nl&quot;&gt;alignment:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;PlaceholderAlignment&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;middle&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;nl&quot;&gt;child:&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Icon&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Icons&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;check_circle&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nl&quot;&gt;size:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;16&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
      &lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
  &lt;span class=&quot;nl&quot;&gt;textDirection:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;TextDirection&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;rtl&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;여기서 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;WidgetSpan&lt;/code&gt;의 배열을 RTL이라는 이유로 뒤집지 않는다. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Transform.translate&lt;/code&gt;로 아이콘을 이동시키거나 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GlobalKey&lt;/code&gt;로 placeholder의 x 좌표를 다시 계산하는 코드도 같은 기준으로 제거한다. Flutter 공식 문서의 변경 설명처럼 Dart 코드에는 콘텐츠의 논리 순서를 남기고, 레이아웃이 반환한 위치를 그대로 사용해야 한다.&lt;/p&gt;

&lt;p&gt;커스텀 렌더러가 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TextPainter&lt;/code&gt;의 placeholder 좌표를 직접 소비한다면 좌표를 좌우 반전하는 부분을 특히 확인한다. 좌표 배열을 별도 캐시에 저장하고 있다면 캐시 키에 Flutter SDK 버전을 넣을 문제가 아니라, 보정 계산 자체를 없애야 한다.&lt;/p&gt;

&lt;h2 id=&quot;golden-테스트는-두-방향을-분리한다&quot;&gt;golden 테스트는 두 방향을 분리한다&lt;/h2&gt;

&lt;p&gt;실제 golden 파일을 실행했다고 가정하지 않고, 출시 전에는 아래 조건을 별도 케이스로 추가한다. 한 줄 텍스트만 보면 위치 오류를 놓치므로 줄바꿈과 LTR 숫자가 섞인 문장을 포함해야 한다.&lt;/p&gt;

&lt;div class=&quot;language-dart highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;testWidgets&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;RTL WidgetSpan keeps logical span order&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;tester&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;async&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;k&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;tester&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;pumpWidget&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Directionality&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
      &lt;span class=&quot;nl&quot;&gt;textDirection:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;TextDirection&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;rtl&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
      &lt;span class=&quot;nl&quot;&gt;child:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Material&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;nl&quot;&gt;child:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Center&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;child:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;DeviceStatusLabel&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()),&lt;/span&gt;
      &lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;

  &lt;span class=&quot;k&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;expectLater&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;find&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;byType&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;DeviceStatusLabel&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;matchesGoldenFile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;goldens/device-status-rtl.png&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;확인 기준은 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;WidgetSpan&lt;/code&gt;이 들어간 화면을 LTR·RTL·혼합 방향으로 나누는 것이다.&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;아랍어 또는 히브리어 문장 안에 아이콘 2개 이상&lt;/li&gt;
  &lt;li&gt;숫자 ID, 영문 제품명, 괄호가 섞인 문장&lt;/li&gt;
  &lt;li&gt;한 줄을 넘기는 좁은 폭&lt;/li&gt;
  &lt;li&gt;Flutter 3.49 기준 golden과 3.50 기준 golden의 차이 검토&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;golden을 기계적으로 전부 덮어쓰면 안 된다. 변경된 픽셀이 placeholder 위치뿐인지 확인하고, 텍스트 자체의 줄바꿈이나 아이콘 크기까지 달라졌다면 별도 회귀로 분리한다. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;WidgetSpan&lt;/code&gt;을 사용하지 않는 LTR 화면의 golden까지 함께 갱신할 이유도 없다.&lt;/p&gt;

&lt;h2 id=&quot;출시-전-판단표&quot;&gt;출시 전 판단표&lt;/h2&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flutter --version&lt;/code&gt;이 3.50이고 다음 검색 결과가 나온다면 이 글의 대상이다.&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;rg &quot;Transform\.translate|WidgetSpan|placeholder|TextDirection\.rtl&quot; lib test
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;발견 내용&lt;/th&gt;
      &lt;th&gt;판단&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;WidgetSpan만 있고 수동 보정 없음&lt;/td&gt;
      &lt;td&gt;RTL 실기기·golden만 확인&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;RTL 전용 역순 생성 있음&lt;/td&gt;
      &lt;td&gt;논리 순서로 되돌리고 golden 갱신&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;placeholder 좌표를 직접 반전&lt;/td&gt;
      &lt;td&gt;반전 로직 제거 후 줄바꿈 검증&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;앱이 RTL을 지원하지 않음&lt;/td&gt;
      &lt;td&gt;해당 변경보다 일반 3.50 업그레이드 점검 우선&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Flutter 공식 변경 문서 기준으로 이 동작은 3.50에 포함됐고, 공개 API 시그니처가 바뀐 변경은 아니다. 따라서 컴파일 오류보다 “업그레이드 후 화면이 조용히 이동하는” 유형에 가깝다. 수정의 핵심은 새 API를 추가하는 것이 아니라 과거 엔진의 잘못된 위치를 맞추려고 넣었던 코드를 걷어내는 데 있다.&lt;/p&gt;

&lt;p&gt;참고 문서: &lt;a href=&quot;https://docs.flutter.dev/release/breaking-changes/widgetspan-rtl-bidi-order&quot;&gt;Flutter WidgetSpan RTL 양방향 순서 변경&lt;/a&gt;, &lt;a href=&quot;https://docs.flutter.dev/release/breaking-changes&quot;&gt;Flutter 3.50 변경 목록&lt;/a&gt;, &lt;a href=&quot;https://api.flutter.dev/flutter/widgets/WidgetSpan-class.html&quot;&gt;WidgetSpan API&lt;/a&gt;&lt;/p&gt;
</description>
        <pubDate>Sat, 14 Nov 2026 00:00:00 +0900</pubDate>
        <link>https://colin-ch-flutter.github.io/2026-11-14/22-00-00-4629375-flutter-350-widgetspan-rtl-golden/</link>
        <guid isPermaLink="true">https://colin-ch-flutter.github.io/2026-11-14/22-00-00-4629375-flutter-350-widgetspan-rtl-golden/</guid>
        
        <category>Flutter</category>
        
        <category>Dart</category>
        
        <category>테스트</category>
        
        <category>접근성</category>
        
        <category>RTL</category>
        
        
      </item>
    
  </channel>
</rss>