Antigravity Agent
3.1 KiB
3.1 KiB
id: FE-SSR-HYDRA-001 category: Unified confidence_score: 1.0 tags: [react, ssr, Hydration, hydration-mismatch, debugging, Frontend-performance, nextjs] last_reinforced: 2026-04-26
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 구조.
- Browser-only APIs: 서버에는 없는
- 해결 및 디버깅 전략:
- 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