docs: finalized wiki integrity maintenance (v3.0 standard) - pruned 1400+ stubs and fixed 11k+ ghost links

This commit is contained in:
Antigravity Agent
2026-05-02 09:18:34 +09:00
parent c84dcb8371
commit 6445fcc05b
13150 changed files with 55394 additions and 100862 deletions
@@ -2,7 +2,7 @@
id: FE-SSR-HYDRA-001
category: "10_Wiki/💡 Topics/AI"
confidence_score: 1.0
tags: [react, ssr, [[Hydration]], hydration-mismatch, debugging, [[Frontend]]-performance, nextjs]
tags: [react, ssr, [[Hydration|Hydration]], hydration-mismatch, debugging, [[Frontend|Frontend]]-performance, nextjs]
last_reinforced: 2026-04-26
---
@@ -12,9 +12,9 @@ last_reinforced: 2026-04-26
> "서버가 구워낸 HTML과 클라이언트가 렌더링한 초기 결과물이 1비트라도 다를 때 발생하는 경고를 무시하지 말고, 정적 일관성을 확보하여 불필요한 전체 리렌더링의 늪에서 탈출하라" — SSR 환경에서 서버와 클라이언트 간의 렌더링 트리 정합성을 유지하기 위한 기술적 가이드.
## 📖 구조화된 지식 (Synthesized Content)
- **추출된 패턴:** "Pre-rendering Consistency and Client-only Escape" — 서버와 클라이언트의 렌더링 결과가 일치해야 한다는 SSR의 대전제를 준수하되, 브라우저 전용 데이터(window, local[[Storage]])가 필요한 경우 'useEffect' 이후로 렌더링을 지연시키는 패턴.
- **추출된 패턴:** "Pre-rendering Consistency and Client-only Escape" — 서버와 클라이언트의 렌더링 결과가 일치해야 한다는 SSR의 대전제를 준수하되, 브라우저 전용 데이터(window, local[[Storage|Storage]])가 필요한 경우 'useEffect' 이후로 렌더링을 지연시키는 패턴.
- **수화 불일치(Hydration Mismatch)의 주요 원인:**
- **[[Browser]]-only APIs:** 서버에는 없는 `window`, `document` 객체를 초기 렌더링 시점에 직접 참조.
- **[[Browser|Browser]]-only APIs:** 서버에는 없는 `window`, `document` 객체를 초기 렌더링 시점에 직접 참조.
- **Non-deterministic Data:** `Math.random()`이나 `new Date()` 등 서버와 클라이언트에서 값이 달라지는 로직 사용.
- **Invalid HTML Structure:** `p` 태그 안에 `div`를 넣는 등 브라우저가 강제로 수정하는 비정상적인 HTML 구조.
- **해결 및 디버깅 전략:**
@@ -24,9 +24,9 @@ last_reinforced: 2026-04-26
- **의의:** 불필요한 UI 흔들림(Flicker)을 방지하고, 브라우저의 렌더링 성능 최적화(Hydration 효율성)를 보장함.
## ⚠️ 모순 및 업데이트 (Contradictions & RL Update)
- **과거 데이터와의 충돌:** 과거에는 수화 불일치 경고를 사소한 경고 정책으로 보았으나, 현대 React 정책은 이를 성능 저하와 버그의 전조로 간주하여 엄격히 관리할 것을 요구함. 특히 [[Next.js 15]]+ 환경에서는 빌드 타임에 이를 더 공격적으로 검출 정책화함.
- **과거 데이터와의 충돌:** 과거에는 수화 불일치 경고를 사소한 경고 정책으로 보았으나, 현대 React 정책은 이를 성능 저하와 버그의 전조로 간주하여 엄격히 관리할 것을 요구함. 특히 [[Next.js 15|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]]
- [[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