React 모달이 모바일에서만 안 닫힐 때

React로 모달을 만들었는데, 데스크톱의 로컬 개발 환경에서는 잘 작동하지만 모바일에서만 닫히지 않는 경험을 하는 경우가 있다. 이는 보통 이벤트 리스너 설정이나 z-index 문제, 또는 터치 이벤트와 클릭 이벤트의 차이 때문이다.

로컬에서 모바일 환경 시뮬레이션

먼저 로컬 개발 환경에서 빌드하고 모바일 폭으로 화면을 줄여서 테스트해보자.

npm run build

빌드 후 npm run start로 운영 환경처럼 실행한다. 그 다음 브라우저 개발자 도구에서 디바이스 시뮬레이션을 켜고, 모바일 크기에서 모달이 제대로 작동하는지 확인해보자.

Chrome의 경우 F12를 눌고 Ctrl+Shift+M (또는 Cmd+Shift+M on Mac)으로 기기 모드를 켤 수 있다.

이벤트 흐름 확인

모달이 닫히지 않는 이유를 찾기 위해, 이벤트 리스너를 다시 살펴보자:

• 배경(backdrop)을 클릭했을 때 onClick 핸들러가 호출되는가
• 닫기 버튼의 onClick 핸들러가 호출되는가
• ESC 키를 눌렀을 때 이벤트가 감지되는가

모바일에서만 문제가 난다면, 터치 이벤트와 클릭 이벤트의 차이일 가능성이 높다. 터치 디바이스에서는 click 이벤트가 300ms 정도 지연될 수 있고, 스크롤 중에 발생한 터치는 click 이벤트로 감지되지 않을 수 있다.

환경에 따른 렌더링 차이

로컬 개발 서버와 운영 서버에서의 CSS나 JavaScript 번들이 다를 수 있다. 특히:

• Tailwind CSS의 안전 목록(safelist)에 모달 클래스가 없어서 운영에서 스타일이 사라진 경우
• 프로덕션 빌드에서 이벤트 리스너가 제대로 바인딩되지 않은 경우
• 모바일 전용 미디어쿼리가 로컬에서는 작동하지만 빌드 후에는 다를 경우

검증: 모바일 기기에서 직접 테스트

로컬 시뮬레이션에서는 작동했다면, 실제 모바일 기기에서 테스트해야 한다:

1. npm run build 후 로컬 IP로 서버를 열어서 (예: http://192.168.x.x:3000) 휴대폰에서 접속
2. 같은 조건에서 모달의 각 기능을 테스트 — 배경 클릭, 버튼 클릭, 스크롤 중 클릭
3. 개발자 도구의 콘솔에서 에러 메시지가 있는지 확인

이 세 가지를 모두 확인한 후, 어디서 문제가 나는지 파악할 수 있다.