Flutter 앱이 에뮬레이터에서는 되는데 실기기에서 안 될 때

로컬 환경과 실기기는 다르다

Flutter로 모바일 앱을 만들다 보면, 에뮬레이터에서는 완벽하게 작동하는데 실기기에서 동작하지 않는 상황을 마주한다. 처음엔 코드 문제인 줄 알고 여기저기 수정해 보지만, 실제로는 환경의 차이에 있을 수 있다.

모바일 앱 디버깅의 핵심은 한 가지 증상에만 집중하지 않는 것이다. 에뮬레이터와 실기기에서 어떻게 다르게 작동하는지, 권한은 제대로 설정되었는지, 빌드 모드는 올바른지를 차례대로 확인해야 한다.

상황을 먼저 정리한다

실기기에서 문제가 나타났을 때, 가장 먼저 할 일은 그 문제가 정확히 어떤 상황에서 나타나는지 파악하는 것이다:

• 먼저 볼 값: API 응답이 제대로 오는가
• 함께 비교할 값: 에뮬레이터에서는 어떻게 작동하는가
• 남겨둘 기록: 빌드 로그, 에러 메시지, 버전 정보

권한이 가장 흔한 원인이다

Android와 iOS 모두 실기기에서는 권한이 중요하다. 에뮬레이터에서는 권한이 자동으로 허용되지만, 실제 기기에서는 런타임 권한을 요청하고 사용자가 승인해야 한다. 네트워크, 파일, 카메라 등 어떤 권한이 필요한지 확인하고, 앱이 그 권한을 제대로 요청하는지 점검해야 한다.

flutter doctor -v
flutter run --verbose

이 명령으로 현재 환경 상태와 빌드 과정을 자세히 볼 수 있다.

빌드 모드를 확인한다

에뮬레이터에서는 대부분 debug 모드로 실행되지만, 실기기에서 문제를 재현하려면 release 모드로도 시도해야 할 때가 있다. 최적화 옵션, 난독화, 리소스 압축 등이 문제를 일으킬 수 있기 때문이다.

체계적으로 확인한다

매번 같은 실수를 반복하지 않으려면 확인 순서를 고정해야 한다:

1. 원래 증상이 같은 조건에서 다시 나타나는지 확인한다
2. 로그에서 바뀐 부분을 명확히 설명할 수 있는지 확인한다
3. 권한, 빌드 모드, API 응답 중 적어도 하나를 최종 확인한다

다음 번을 위해 기록한다

실기기 문제를 해결한 후, "어떤 환경 설정이 원인이었는가"를 짧게 정리해두면, 비슷한 문제가 나올 때 대응 속도가 크게 빨라진다.