Flutter Android 뒤로가기 버튼이 안 먹히는 문제 해결기

Flutter Android 뒤로가기 버튼이 안 먹히는 문제 해결기

TL;DR: Android 13+ 기기에서 Flutter 앱의 뒤로가기 버튼이 무시되고 앱이 바로 종료되는 현상은 AndroidManifest.xml에 android:enableOnBackInvokedCallback="false" 한 줄로 해결된다.

---

증상

• Android 기기에서 앱 실행 직후 뒤로가기 버튼을 누르면 앱이 즉시 종료됨
• PopScope, BackButtonListener, WillPopScope 등 Flutter 위젯이 전혀 반응하지 않음
• WidgetsBindingObserver.didPopRoute()도 호출되지 않음
• back_button_interceptor 같은 서드파티 패키지도 무효
• 다른 화면으로 갔다 오면 갑자기 동작하는 등 불규칙한 패턴

원인: Android Predictive Back Gesture

Android 13 (API 33)부터 도입된 기능

Android 13부터 Predictive Back Gesture(예측형 뒤로가기)가 도입되었다. 이 기능은 사용자가 뒤로가기 제스처를 할 때 "이전 화면 미리보기"를 보여주는 애니메이션을 제공한다.

문제는 이 기능이 활성화되면 Android 시스템이 Flutter 프레임워크보다 먼저 뒤로가기 이벤트를 처리한다는 것이다.

이벤트 처리 순서 비교

정상 (Predictive Back 비활성화):

시스템 뒤로가기 → Flutter Engine → WidgetsBinding.handlePopRoute()
→ Router/Navigator → PopScope/BackButtonListener → 개발자 코드

문제 상황 (Predictive Back 활성화):

시스템 뒤로가기 → Android 시스템이 직접 처리 → 앱 종료
                  (Flutter에 이벤트가 전달되지 않음!)

왜 최신 Flutter 프로젝트에서 발생하는가?

Flutter 3.x 이상에서 flutter create로 생성한 프로젝트는 AndroidManifest.xml에 enableOnBackInvokedCallback 속성이 명시되어 있지 않다. 이 경우 Android 13+ 기기에서는 시스템 기본 동작에 따라 Predictive Back이 활성화될 수 있으며, 특히 최신 빌드 도구(targetSdkVersion 34+)를 사용하면 기본값이 true로 동작한다.

해결 방법

AndroidManifest.xml 수정

<!-- android/app/src/main/AndroidManifest.xml -->
<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTop"
    ...
    android:enableOnBackInvokedCallback="false">  <!-- 이 줄 추가 -->

위치: <activity> 태그의 속성으로 추가한다.

주의사항

• 이 변경은 네이티브 설정이므로 Hot Reload/Hot Restart로는 적용되지 않는다
• 반드시 앱을 완전히 종료하고 flutter run으로 다시 빌드해야 한다
• debug, profile, main 세 폴더의 AndroidManifest.xml 중 main만 수정하면 된다

디버깅 과정에서 시도했지만 효과 없었던 것들

시도	결과
PopScope(canPop: false)	이벤트 자체가 Flutter에 안 옴
GoRouter BackButtonListener	동일 - 이벤트 미전달
WidgetsBindingObserver.didPopRoute()	동일 - 콜백 미호출
back_button_interceptor 패키지	동일 - 패키지도 무효
GoRouter 제거 후 순수 MaterialApp	동일 - 라우터 문제 아님
PopScope 제거	일부 개선되나 근본 해결 안됨

핵심: Flutter 레이어의 어떤 코드도 효과가 없다. Android 네이티브 레벨에서 이벤트가 차단되기 때문이다.

향후 대응

Flutter에서 Predictive Back을 지원하려면?

Flutter 팀은 Predictive Back을 점진적으로 지원하고 있다. PopScope 위젯이 그 일환이다. 향후 Flutter가 Predictive Back을 완전히 지원하게 되면 enableOnBackInvokedCallback="true"로 전환하고 PopScope를 적극 활용할 수 있다.

현재 권장 사항:

1. 당분간은 false로 유지하여 안정적인 뒤로가기 동작을 보장
2. Flutter의 Predictive Back 지원이 안정화되면 true로 전환 검토
3. 전환 시 모든 화면에서 PopScope가 올바르게 설정되어 있는지 확인

체크리스트

• android:enableOnBackInvokedCallback="false" 설정 확인
• 앱의 모든 탭/화면에서 뒤로가기 테스트
• 앱 최초 진입 직후 뒤로가기 테스트 (이 시나리오가 가장 잘 놓침)
• Android 13 미만 기기에서도 정상 동작 확인

참고 자료

• Android Predictive Back Gesture 공식 문서
• Flutter PopScope 클래스
• Flutter GitHub Issue #109513 - Predictive back navigation

---

작성일: 2026-02-07
환경: Flutter 3.x, Android 13+ (API 33+), GoRouter 14.x