Flutter 실기기에서 디버깅할 때 확인해야 할 것들

처음부터 완벽한 해결책을 찾으려고 하면 오히려 시간이 더 걸린다. 실기기에서 생기는 문제는 일반적인 몇 가지 원인 중 하나인 경우가 많다.

개발 환경 진단

실기기 테스트 전에 개발 환경을 먼저 확인한다:

flutter doctor -v

이 명령으로 Xcode, Android SDK, CocoaPods 등의 설치 상태와 버전을 확인한다. 버전 불일치는 예상치 못한 버그의 원인이 될 수 있다. 특히 최근에 Xcode를 업데이트했거나 Android Studio를 설치한 경우, doctor 출력이 변할 수 있다.

API 응답 확인

실기기에서 앱을 실행할 때, API가 정상적으로 응답하는지 확인한다. 로컬 개발 중에는 localhost API를 사용하지만, 실기기는 다른 네트워크 환경이다:

• 같은 WiFi에 연결되어 있는가?
• API 서버의 HTTPS 인증서를 인정하는가?
• 데이터 로밍을 사용할 때와 WiFi를 사용할 때 동작이 다른가?

실기기 로그 읽기

Verbose 모드로 실행하면 상세한 로그를 볼 수 있다:

flutter run --verbose

이 출력에서 "Building", "Connected device", "I/flutter" 같은 섹션을 찾는다. 에러가 발생하면 보통 "E/flutter" 또는 "ERROR" 로그가 명확하게 표시된다.

빌드 모드 확인

Debug, Release, Profile 모드는 각각 다르게 작동한다:

flutter run --release  # 최적화된 릴리스 빌드
flutter run --profile  # 성능 측정 가능, 디버깅 정보 포함

Release 모드에서만 문제가 생기면, 보통 디버그 정보 제거나 트리셰이킹 때문이다. Profile 모드는 성능 분석을 하면서도 로그를 볼 수 있어서 중간 단계 검증에 유용하다.

권한 확인

앱이 필요한 권한을 가지고 있는지 확인한다:

flutter devices  # 연결된 기기 목록

연결된 기기가 맞는지 확인한 후, 카메라, 마이크, 위치 정보 등의 권한이 앱에 부여되었는지 확인한다. 실기기에서는 권한 요청 대화가 앱의 첫 실행 때 나타날 수 있다.

단계별 검증

1. 증상을 다시 한 번 재현한다. 매번 나타나는가? 특정 화면에서만 나타나는가?
2. 로그의 마지막 라인이나 에러 메시지를 정확히 읽는다. 스택 트레이스에서 실제 문제가 발생한 곳을 찾는다.
3. 같은 빌드를 다른 실기기에서 테스트해본다. 특정 폰 모델에서만 문제가 생기는지 확인한다.

마무리

해결 자체도 중요하지만, 어떤 값이 달라졌는지를 정확히 설명할 수 있는 상태가 더 중요하다. 그러면 다음에 비슷한 문제가 나올 때 더 빨리 처리할 수 있다.