Hydration Mismatch and SSR Debugging (수화 불일치 및 SSR 디버깅)

📌 한 줄 통찰 (The Karpathy Summary)

"서버가 구워낸 HTML과 클라이언트가 렌더링한 초기 결과물이 1비트라도 다를 때 발생하는 경고를 무시하지 말고, 정적 일관성을 확보하여 불필요한 전체 리렌더링의 늪에서 탈출하라" — SSR 환경에서 서버와 클라이언트 간의 렌더링 트리 정합성을 유지하기 위한 기술적 가이드.

📖 구조화된 지식 (Synthesized Content)

추출된 패턴: "Pre-rendering Consistency and Client-only Escape" — 서버와 클라이언트의 렌더링 결과가 일치해야 한다는 SSR의 대전제를 준수하되, 브라우저 전용 데이터(window, localStorage)가 필요한 경우 'useEffect' 이후로 렌더링을 지연시키는 패턴.
수화 불일치(Hydration Mismatch)의 주요 원인:
- Browser-only APIs: 서버에는 없는 window, document 객체를 초기 렌더링 시점에 직접 참조.
- Non-deterministic Data: Math.random()이나 new Date() 등 서버와 클라이언트에서 값이 달라지는 로직 사용.
- Invalid HTML Structure: p 태그 안에 div를 넣는 등 브라우저가 강제로 수정하는 비정상적인 HTML 구조.
해결 및 디버깅 전략:
- Isomorphic Consistency: 공통 상수나 환경 변수를 사용하여 양쪽 환경의 초기 값을 일치시킴.
- Two-pass Rendering: isMounted 상태 등을 활용하여 서버 렌더링 시에는 공통 UI를, 클라이언트 마운트 이후에 브라우저 전용 UI를 렌더링.
- Suppression Tag: 극히 제한적인 상황에서만 suppressHydrationWarning 속성 사용.
의의: 불필요한 UI 흔들림(Flicker)을 방지하고, 브라우저의 렌더링 성능 최적화(Hydration 효율성)를 보장함.

⚠️ 모순 및 업데이트 (Contradictions & RL Update)

과거 데이터와의 충돌: 과거에는 수화 불일치 경고를 사소한 경고 정책으로 보았으나, 현대 React 정책은 이를 성능 저하와 버그의 전조로 간주하여 엄격히 관리할 것을 요구함. 특히 Next.js 15+ 환경에서는 빌드 타임에 이를 더 공격적으로 검출 정책화함.
정책 변화: Antigravity 프로젝트는 모든 SSR 컴포넌트에 대해 'Zero Hydration Warning' 정책을 시행하며, 브라우저 전용 로직은 반드시 전용 커스텀 훅(useIsMounted)을 통해서만 처리하도록 강제함.

🔗 지식 연결 (Graph)

Web-Rendering-Strategies-CSR-vs-SSR, Server-Side-Rendering-SSR, Nextjs-App-Router-Architecture, Frontend-Debugging-and-Testing
Raw Source: 00_Raw/Hydration Mismatch.md

2.9 KiB Raw Blame History

Hydration Mismatch and SSR Debugging (수화 불일치 및 SSR 디버깅)

📌 한 줄 통찰 (The Karpathy Summary)

📖 구조화된 지식 (Synthesized Content)

⚠️ 모순 및 업데이트 (Contradictions & RL Update)

🔗 지식 연결 (Graph)

2.9 KiB

Raw Blame History