React 모바일 화면에서 레이아웃이 깨질 때 배포 전 확인사항

로컬 개발 환경에서는 문제없던 모바일 레이아웃이 실제 배포 환경에서 깨질 때가 있다. 이런 상황은 보통 빌드 최적화, 캐시, 뷰포트 설정의 차이에서 비롯된다.

모바일 환경에서 먼저 확인할 것

배포 전에 로컬에서 모바일 폭을 정확히 시뮬레이션해보자. 브라우저 개발자 도구의 Device Toolbar을 사용해서:

npm run build
# 브라우저에서 모바일 폭(375px, 768px 등)과 터치 입력 흐름을 확인한다

특히 입력 필드가 있다면, 키보드 등장 시 레이아웃이 어떻게 변하는지 직접 확인해야 한다. 로컬 시뮬레이션과 실제 모바일 기기의 동작이 다를 수 있다.

에러 문구와 렌더링 조건 확인

React 컴포넌트가 특정 뷰포트에서만 에러를 던지는 경우도 있다. 브라우저 콘솔에 에러가 있는지, 특정 화면 크기에서만 나타나는지 추적해보자.

렌더링 조건(window.innerWidth 체크, 미디어 쿼리 등)이 로컬과 배포 환경에서 다르게 평가될 수 있다.

배포 전 체크리스트

1. 현재 정상 상태 정의 — 모바일 375px, 768px에서 모두 정상인지 스크린샷 저장
2. 에러 메시지 확인 — 콘솔에 경고나 에러가 있는지 확인
3. 이벤트 흐름 검증 — 터치, 클릭, 입력 이벤트가 예상대로 작동하는지
4. 빌드 최적화 효과 확인 — npm run build로 최적화된 상태에서 다시 확인
5. 배포 후 재검증 — 같은 모바일 환경에서 다시 한 번 확인

같은 문제가 반복되면 먼저 현재 값을 기록하고, 하나씩 비교하면 원인이 빠르게 좁혀진다.