Flutter 모바일 앱에서 key prop으로 인한 레이아웃 깨짐 문제

Flutter로 리스트를 만들 때 항목을 추가하거나 제거하면 이상하게 레이아웃이 깨진다. StatefulWidget의 상태가 뒤섞이거나, 텍스트가 잘못된 항목에 나타나거나.

이건 대부분 key prop이 없거나 잘못됐을 때다. 하지만 key 설정 자체도 환경과 빌드 모드에 따라 다르게 동작할 수 있다.

먼저 flutter doctor로 환경 확인

flutter doctor -v
flutter run --verbose

Flutter 버전, Dart 버전, SDK 설정, 플러그인 호환성. 이 모든 게 출력된다. 혼자 개발할 때는 이런 환경 설정을 자주 놓친다.

API 응답과 로컬 데이터 비교

서버에서 받은 데이터 구조가 정말로 유니크한 id를 가지고 있는가? 같은 항목이 여러 개 들어왔는가? 로컬 테스트 데이터와 실제 API 응답이 다를 수 있다.

빌드 모드로 확인해보기

Debug 모드에서는 괜찮은데 Release 빌드에서 문제가 나올 수도 있다. 또는 반대로.

원래 증상이 같은 조건에서 다시 나는지 확인한다. 리스트를 추가하고 삭제했을 때 같은 방식으로 깨지는가? 로그나 응답에서 달라진 부분을 적는다. 그러다 보면 key 설정이나 위젯 구조에서 실제 문제를 찾는다. 그 기록이 있으면 다음 번엔 훨씬 빠르게 같은 문제를 해결할 수 있다.