배포 후 모달 UI가 깨져 보일 때 디버깅하기

배포 후에 갑자기 모달이 안 보인다고 한다. 로컬에서는 잘 작동하는데 말이다. 보통 상태 초기화 문제나 CSS 로드 순서 때문이다.

먼저 모바일 폭에서 테스트한다

브라우저 DevTools에서 모바일 뷰로 전환해서 모달이 나타나는지 본다.

# 로컬 dev 환경
npm run dev
# 브라우저: F12 → Device Toolbar → 모바일 폭 선택

PC에선 되는데 모바일에선 안 보이면 CSS media query나 viewport 설정 문제일 수 있다.

React DevTools로 상태를 확인한다

React DevTools 확장을 설치하고 모달 상태를 본다:

1. 모달을 열 때 isOpen 상태가 true로 바뀌는가
2. 부모 컴포넌트에서 상태가 전달되는가
3. 모달 렌더링이 조건부로 이루어지는가 (잘못된 && 연산자 등)

상태 변화가 일어나지 않으면 이벤트 핸들러 자체가 작동하지 않는 거다.

브라우저 콘솔에서 에러를 확인한다

DevTools → Console에서:

• 에러 메시지 (빨간색)
• 경고 (노란색)

특히 "Cannot read property 'addEventListener' of null" 같은 메시지가 있으면 DOM 요소가 없다는 뜻이다.

# 브라우저 콘솔에서 직접 테스트
const modal = document.querySelector('[role="dialog"]')
console.log(modal)  // null이면 DOM에 없는 것

production 빌드로 로컬 테스트한다

dev 환경과 production 빌드는 다르다.

npm run build
npm run start

production 모드에서:

• Minified 코드가 다르게 작동할 수 있다
• 환경 변수가 다르게 로드된다
• Source map이 없어서 에러 추적이 어렵다

이 단계에서 문제가 재현되면 배포 환경과 같은 조건에서 디버깅할 수 있다.

CSS와 구조를 HTML에서 직접 본다

브라우저에서 요소를 검사한다 (Inspect Element):

1. 모달 container의 display가 none인가
2. z-index가 백그라운드보다 낮은가
3. position이 잘못 설정되어 있는가

CSS-in-JS 라이브러리 (styled-components, emotion)를 사용한다면 스타일이 실제로 적용되는지 확인해야 한다.

# 브라우저 콘솔에서
const modal = document.querySelector('[role="dialog"]')
const style = window.getComputedStyle(modal)
console.log(style.display, style.zIndex, style.position)

상태 초기화 순서를 점검한다

리렌더링 중에 상태가 잘못 초기화될 수 있다:

// 문제: 매번 모달이 닫히는 상태로 초기화
function App() {
  const [isOpen, setIsOpen] = useState(false)  // 이게 계속 실행된다
}

// 해결: useEffect로 한 번만 초기화
function App() {
  const [isOpen, setIsOpen] = useState(false)
  useEffect(() => {
    // 초기 설정 로직
  }, [])
}

마지막으로 네트워크를 확인한다

DevTools → Network에서:

• CSS 파일이 제대로 로드되는가 (404 아닌가)
• JavaScript 에러로 파일 로드가 중단되지 않았는가

느린 네트워크에서는 CSS가 늦게 로드되어 모달이 보이지 않을 수 있다. 이 경우 critical CSS 최적화가 필요하다.