Flutter 실기기 디버깅할 때 확인하는 순서

실기기에서 발생한 문제를 해결할 때 가장 중요한 건 무작정 코드를 수정하는 것보다 현상을 명확히 파악하는 것이다. 재현 조건을 먼저 잡아두면 원인 후보가 자연스럽게 줄어든다.

가장 먼저 봐야 할 것

현상이 발생했을 때 화면만 보지 말고 로그, API 응답, 에러 메시지까지 함께 확인해야 한다. 로컬에서는 괜찮던 설정도 배포 환경이나 실기기에서는 다르게 동작할 수 있다.

먼저 확인할 값들:

• API 응답 코드와 내용
• 실기기 로그 (flutter logs)
• 빌드 모드 (debug, release, profile)
• 권한 설정 (AndroidManifest.xml, Info.plist)
• 네트워크 환경 (Wi-Fi, 모바일 데이터 차이)

doctor로 개발 환경 확인

기본 설정부터 점검한다. Flutter doctor는 깔려 있는 SDK, 연결된 디바이스, 빌드 도구의 상태를 한눈에 보여준다.

flutter doctor -v

여기서 [!] 표시가 있으면 해당 부분을 먼저 확인해야 한다. 특히 Android toolchain이나 iOS toolchain에 문제가 있으면 같은 코드도 다르게 동작할 수 있다.

실기기에서 직접 실행해보기

flutter run --verbose로 상세 로그를 보면서 실행하면 문제가 어느 단계에서 발생하는지 명확해진다. 빌드 과정에서 실패하는지, 런타임에 크래시하는지에 따라 원인이 달라진다.

flutter run --verbose
# 또는 특정 디바이스 지정
flutter run -d <device-id> --verbose

로그에서 주목할 부분:

• 컴파일 에러나 경고
• 플러그인 초기화 실패
• 네트워크 요청 실패
• 권한 거부

같은 조건에서 재현 가능한지 확인

한 번 발생한 현상이 매번 나타나는지 확인하는 것이 중요하다. 간헐적 에러라면 데이터 경쟁 조건이나 메모리 문제일 가능성이 높다.

1. 앱을 종료하고 다시 실행한다
2. 앱 데이터를 지우고 실행한다 (flutter run 전에 수동으로 삭제)
3. 다른 네트워크 환경에서 시도한다
4. 다른 디바이스에서 시도한다

로그와 응답으로 원인을 특정하기

실기기 로그를 따로 저장하면서 현상을 기록해두면 다음 작업이 훨씬 빠르다.

flutter logs > debug.log

API 응답이 문제라면 Network tab을 열어서 요청과 응답을 확인한다. 빌드나 권한이 문제라면 에러 메시지에 명확하게 나타난다.

마지막 확인

수정 후에는 반드시 같은 방식으로 다시 테스트한다. 로컬에서 완벽해도 배포 환경이나 다른 디바이스에서 같은 문제가 나타날 수 있기 때문이다. 현상 → 원인 파악 → 수정 → 재현 불가 확인까지 한 세트로 생각해야 다음에 비슷한 문제를 빠르게 처리할 수 있다.