[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -2,92 +2,172 @@
|
||||
id: wiki-2026-0508-hydration-mismatch-and-ssr-debug
|
||||
title: Hydration Mismatch and SSR Debugging
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [FE-SSR-HYDRA-001]
|
||||
aliases: [Hydration Mismatch, SSR Debug, Hydration Error]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 1.0
|
||||
tags: [react, ssr, Hydration, hydration-mismatch, debugging, Frontend-performance, nextjs]
|
||||
confidence_score: 0.9
|
||||
verification_status: applied
|
||||
tags: [react, ssr, hydration, debugging]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-04-26
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
language: typescript
|
||||
framework: react-next
|
||||
---
|
||||
|
||||
# Hydration Mismatch and SSR Debugging (수화 불일치 및 SSR 디버깅)
|
||||
# Hydration Mismatch and SSR Debugging
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> "서버가 구워낸 HTML과 클라이언트가 렌더링한 초기 결과물이 1비트라도 다를 때 발생하는 경고를 무시하지 말고, 정적 일관성을 확보하여 불필요한 전체 리렌더링의 늪에서 탈출하라" — SSR 환경에서 서버와 클라이언트 간의 렌더링 트리 정합성을 유지하기 위한 기술적 가이드.
|
||||
## 매 한 줄
|
||||
> **"매 server-rendered HTML 과 매 client first render 가 매 다르면 매 React 가 매 throw — 매 일관된 input 이 매 핵심."**. 매 typical 원인: Date.now / Math.random / window 접근 / locale / 매 third-party DOM 조작. React 19 부터 매 error message 가 매 어떤 attribute 가 매 mismatch 인지 매 정확히 표시.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
- **추출된 패턴:** "Pre-rendering Consistency and Client-only Escape" — 서버와 클라이언트의 렌더링 결과가 일치해야 한다는 SSR의 대전제를 준수하되, 브라우저 전용 데이터(window, local[[Storage|Storage]])가 필요한 경우 'useEffect' 이후로 렌더링을 지연시키는 패턴.
|
||||
- **수화 불일치(Hydration Mismatch)의 주요 원인:**
|
||||
- **[[Browser|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 & Updates)
|
||||
- **과거 데이터와의 충돌:** 과거에는 수화 불일치 경고를 사소한 경고 정책으로 보았으나, 현대 React 정책은 이를 성능 저하와 버그의 전조로 간주하여 엄격히 관리할 것을 요구함. 특히 [[Next.js 15|Next.js 15]]+ 환경에서는 빌드 타임에 이를 더 공격적으로 검출 정책화함.
|
||||
- **정책 변화:** Antigravity 프로젝트는 모든 SSR 컴포넌트에 대해 'Zero Hydration Warning' 정책을 시행하며, 브라우저 전용 로직은 반드시 전용 커스텀 훅(`useIsMounted`)을 통해서만 처리하도록 강제함.
|
||||
### 매 원인 분류
|
||||
- **Time / random**: server 의 매 시각 ≠ client 의 매 시각.
|
||||
- **Locale / timezone**: Intl.DateTimeFormat 의 매 다른 결과.
|
||||
- **Window / document**: server 에 매 없음.
|
||||
- **User-agent branching**: useragent 의 매 다른 처리.
|
||||
- **Third-party script**: AdSense, Cookiebot 의 매 DOM 변경.
|
||||
- **Browser extension**: Grammarly, Dark Reader 의 매 inject.
|
||||
- **Conditional rendering on `typeof window`**: 매 안티패턴.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- [[Web-Rendering-Strategies-CSR-vs-SSR|Web-Rendering-Strategies-CSR-vs-SSR]], Server-Side-Rendering-SSR, [[Nextjs-App-Router-Architecture|Nextjs-App-Router-Architecture]], [[Frontend-Debugging-and-Testing|Frontend-Debugging-and-Testing]]
|
||||
- **Raw Source:** 00_Raw/Hydration Mismatch.md
|
||||
### 매 React 의 매 행동 (19)
|
||||
- 매 mismatch detection — 매 server HTML 을 매 polluted attribute 로 매 표시.
|
||||
- 매 partial recovery — 매 mismatch boundary 만 매 client re-render.
|
||||
- 매 보존되는 attribute (data-, aria-, custom): 매 dev warning.
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
### 매 Debug 도구
|
||||
- **Next.js**: `?_rsc_no_cache` 로 매 server payload 확인. `next dev` 의 매 colored diff.
|
||||
- **React DevTools**: Profiler — hydration milestone.
|
||||
- **Browser**: 매 view-source vs DOM inspect 비교.
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
### 매 응용
|
||||
1. e-commerce — 매 product price (locale), cart count (cookie).
|
||||
2. Auth — 매 logged-in / logged-out 분기.
|
||||
3. A/B test — 매 server vs client variant 의 매 일치.
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
## 💻 패턴
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
### Detect mismatch source (Next.js 15)
|
||||
```tsx
|
||||
// Bad — Date.now() differs
|
||||
function Now() { return <span>{Date.now()}</span>; }
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
// Good — pass server time as prop, render same on both
|
||||
function Now({ serverTime }: { serverTime: number }) {
|
||||
return <span suppressHydrationWarning>{new Date(serverTime).toISOString()}</span>;
|
||||
}
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### useEffect for client-only side effects
|
||||
```tsx
|
||||
function ClientGreeting() {
|
||||
const [name, setName] = useState<string | null>(null);
|
||||
useEffect(() => setName(localStorage.getItem('name')), []);
|
||||
if (!name) return null; // server returns null, client fills after mount
|
||||
return <p>Hi {name}</p>;
|
||||
}
|
||||
```
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### dynamic() with ssr: false (Next.js)
|
||||
```tsx
|
||||
import dynamic from 'next/dynamic';
|
||||
const Chart = dynamic(() => import('./Chart'), { ssr: false });
|
||||
// Renders nothing on server, only on client
|
||||
```
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Avoid Math.random in render
|
||||
```tsx
|
||||
// Bad
|
||||
function Card() { return <div data-id={Math.random()}>...</div>; }
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
// Good — useId
|
||||
function Card() { const id = useId(); return <div id={id}>...</div>; }
|
||||
```
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
### suppressHydrationWarning (last resort)
|
||||
```tsx
|
||||
<time dateTime={iso} suppressHydrationWarning>
|
||||
{new Intl.DateTimeFormat('ko').format(new Date(iso))}
|
||||
</time>
|
||||
```
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
### Diagnose third-party DOM mutation
|
||||
```tsx
|
||||
useEffect(() => {
|
||||
const obs = new MutationObserver(records => {
|
||||
for (const r of records) {
|
||||
console.warn('mutation', r.target, r.attributeName, r.addedNodes);
|
||||
}
|
||||
});
|
||||
obs.observe(document.body, { subtree: true, childList: true, attributes: true });
|
||||
return () => obs.disconnect();
|
||||
}, []);
|
||||
```
|
||||
|
||||
### Locale-stable rendering
|
||||
```tsx
|
||||
// Server and client must agree — pass timezone explicitly
|
||||
const fmt = new Intl.DateTimeFormat('ko-KR', { timeZone: 'Asia/Seoul' });
|
||||
return <span>{fmt.format(new Date(props.iso))}</span>;
|
||||
```
|
||||
|
||||
### Replay server HTML offline
|
||||
```bash
|
||||
# Capture server HTML
|
||||
curl -s https://app.example.com/page > server.html
|
||||
# Open in fresh browser, compare with hydrated DOM via outerHTML diff
|
||||
```
|
||||
|
||||
### React 19 onRecoverableError
|
||||
```tsx
|
||||
hydrateRoot(document, <App />, {
|
||||
onRecoverableError(err, info) {
|
||||
fetch('/log/hydration-error', {
|
||||
method: 'POST',
|
||||
body: JSON.stringify({ msg: String(err), digest: info.digest }),
|
||||
});
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 원인 | Fix |
|
||||
|---|---|
|
||||
| 매 time / random | useId / passed-down server value |
|
||||
| 매 locale / TZ | 매 explicit Intl 의 매 timeZone |
|
||||
| 매 window / localStorage | 매 useEffect 후 setState |
|
||||
| 매 SSR 무가치 component | 매 dynamic ssr:false |
|
||||
| 매 third-party inject | 매 suppressHydrationWarning + 매 root 외부 |
|
||||
| 매 extension (Grammarly) | 매 무시 — 매 알려진 false positive |
|
||||
|
||||
**기본값**: 매 server / client 를 매 동일 input 으로 매 강제. 매 last resort suppressHydrationWarning.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[Hydration]] · [[SSR]]
|
||||
- 변형: [[Selective Hydration]] · [[Streaming SSR]]
|
||||
- 응용: [[Next.js App Router]] · [[Remix]] · [[Astro]]
|
||||
- Adjacent: [[useId]] · [[useEffect]] · [[React 19]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: 매 hydration error stack 분석, 매 SSR 코드 review, 매 timezone bug 진단.
|
||||
**언제 X**: 매 pure CSR — 매 hydration 자체 X.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **`typeof window !== 'undefined'` in render**: 매 server / client output 차이 — 매 mismatch 보장.
|
||||
- **Date.now() in render**: 매 항상 mismatch.
|
||||
- **suppressHydrationWarning 남발**: 매 진짜 bug 숨김.
|
||||
- **try/catch around hydrateRoot 만**: 매 root cause 추적 X.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (React 19 docs — Hydration Errors, Next.js 15 docs).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — 매 mismatch 원인 + Next.js 15 debug |
|
||||
|
||||
Reference in New Issue
Block a user