🚀 Next.js 4장: Hydration과 Mismatch — 내 화면이 찢어진 이유

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ 비유로 먼저 이해하기
• 🧩 Hydration (수화) — 빈 HTML에 생명 불어넣기 🟢
• 🚨 Text content did not match (Mismatch 에러의 공포) 🟡
• 🛡️ 우아한 해결책: useEffect + State 마운트 지연 🟡
• 🌙 다크테마 mounted 패턴의 성능 트레이드오프와 베스트 프랙티스 🟡
• 💥 에러 해결 카탈로그
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 15분(전체) / 핵심 파트만: 8분

🗺️ 이 문서의 흐름
Hydration 개념 원리 → 프론트엔드 최악의 에러 Mismatch → 원인 분석 → 베스트 프랙티스(영수네 커뮤니티 예제)

🎯 이 문서를 다 읽으면 할 수 있는 것

• Next.js에서 브라우저 객체(window, localStorage)를 컴포넌트 최상단에서 읽었을 때 화면이 터지는 원리를 설명할 수 있다.
• Hydration 에러를 회피하는 클라이언트 마운트 보장 패턴(Mount Guarantee Pattern)을 스스로 작성할 수 있다.

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 영철(새로 온 주니어): "어? 유저의 브라우저 언어 세팅에 맞춰서 '환영합니다' / 'Welcome' 을 보여주려고 navigator.language 를 썼는데요. 자꾸 화면은 멀쩡한데 콘솔에 시뻘건 'Text content did not match' 에러가 쏟아져요! 😭"
• 영호(FE 리드): "영철 님... 서버(영국 Vercel)에서 구워 보낸 '빈대떡(HTML)' 이랑, 브라우저가 다시 구워본 '빈대떡' 의 토핑이 다르면 리액트는 멘붕에 빠지거든요. 서버는 접속자가 누군지 몰라요!"

🤔 왜 알아야 하는가

Next.js 환경을 처음 다루는 React 개발자가 마주하게 되는 가장 끔찍하고 거대한 에러 메시지 1위 는 누가 뭐라 해도 "Hydration Error" 일 거야.

기본적인 React(CSR) 세상에서는 브라우저가 텅 빈 HTML을 받고, 하얀 화면 상태에서 본인이 직접 UI를 그렸어. 본인이 만드는 거니까 불일치할 일이 없었지.

하지만 Next.js에서는 이야기가 달라. 서버가 먼저 완벽한 모양의 "HTML 껍데기" 를 그려서 배달해줘. 그리고 브라우저는 이 껍데기 위에 뒤늦게 도착한 자바스크립트 물(Hydrate) 을 부어 생명을 살려야 해.

이때 껍데기 그림(서버에서 본 세상)과 내용물(브라우저가 본 세상)이 단 1픽셀, 단 1글자라도 다르면, React는 "해킹당했거나 코드가 심각하게 꼬였다!" 고 판단하며 앱을 폭파시켜버려. 이 두 세계의 불일치 를 다룰 줄 모르면 영원히 원인 모를 UI 버그에 시달리게 될 거야.

🏗️ 비유로 먼저 이해하기

🧒 5살에게 설명한다면? (이케아 조립 가이드)

SSR(서버 사이드 렌더링) 은 이케아 공장에서 미리 찍어놓은 완성 사진(HTML 껍데기) 을 배달해주는 거야. 눈에는 완성된 소파처럼 보여.

Hydration(수화) 은 그 소파에 실제로 앉을 수 있게 다리를 조립하고 쿠션을 끼우는 작업이야(자바스크립트 이벤트 연결). 이 작업이 끝나야 비로소 버튼도 눌리고 클릭도 돼.

Mismatch 에러 는 이런 상황이야. 공장에서 "빨간 소파" 사진을 보냈는데, 내 조립 설명서(브라우저 JS) 에는 "파란 소파를 조립하세요" 라고 적혀 있는 거야. 리액트가 "이거 다른 제품이잖아! 내가 아는 부품이랑 안 맞아!" 하면서 조립을 거부하는 대참사지.

🧩 Hydration (수화) — 빈 HTML에 생명 불어넣기 🟢

이게 뭔가? & 왜 필요한가?

Next.js가 자랑하는 빠른 초기 로딩 속도의 비밀은 서버에서 HTML 요소를 미리 떡하니 다 그려서 보내는 것에 있어. 그 덕에 눈으로는 완벽한 사이트를 볼 수 있지.
다만 이 상태의 사이트는 클릭 버튼을 눌러도 반응이 없는 '식물인간' 상태야. 자바스크립트가 아직 버튼에 묶이지(Bind) 않았거든.

브라우저가 이 껍데기를 받고 나서야 번들 자바스크립트 파일을 다운로드해. 그리고 HTML 요소마다 찰흙을 바르듯 이벤트 리스너(onClick)를 맵핑해서 살아 움직이게 만들어. 이 과정이 메마른 껍데기에 촉촉하게 수분을 공급한다는 뜻으로 Hydration(수화) 이라고 불러.

🚨 Text content did not match (Mismatch 에러의 공포) 🟡

가장 악명 높은 에러는 서버에서 렌더링할 때 뱉어낸 결과물과, 나중에 클라이언트에서 그 코드 라인을 다시 실행했을 때 기대하는 결과물이 서로 다를 때 발생해.

❌ 영철이의 폭탄 코드: 로컬스토리지 맹신

영철이는 사용자가 설정한 다크모드 테마를 꺼내오고 싶었어.

// ❌ 순진한 코드 (Naive Approach) - 클라이언트 컴포넌트
'use client'
 
export default function ThemeGreeting() {
  // 이 코드는 브라우저에서는 완벽하게 "dark"를 꺼낸다.
  // 하지만 이 코드가 "Next.js 서버"에서 읽힐 때는 로컬스토리지가 없으므로 터지거나 null이 된다.
  const theme = typeof window !== 'undefined' ? localStorage.getItem('theme') : 'light';
 
  return (
    <div className={theme === 'dark' ? 'bg-black text-white' : 'bg-white text-black'}>
      안녕하세요, 영수네 커뮤니티입니다!
    </div>
  )
}

[리액트 엔진이 화를 내는 과정]

1. 서버(Node.js): "음, window가 없군. 나는 이 컴포넌트를 무조건 light 하얀색 테마의 HTML 껍데기로 만들어서 보내야지."
2. 브라우저: 하얀 껍데기를 받았어. 눈에는 하얀 화면이 보여.
3. 브라우저 (Hydrate 시작): "자 이제 물감을 칠해볼까? 어? 내 자바스크립트는 theme 변수에 로컬스토리지 글자인 'dark'가 담긴다고 말하네! 나는 까만 바탕을 그려야 하는데 서버 놈은 하얀 바탕을 줬잖아?! Text content did not match! 서버와 클라이언트의 결과가 다르다!"

🛡️ 우아한 해결책: useEffect + State 마운트 지연 🟡

시니어 개발자인 영호는 이런 상황에서 영원 불변의 해결책인 마운트 보장 패턴(Mount Guarantee Pattern) 을 사용해.

💡 핵심 논리
브라우저(로컬스토리지, 윈도우 너비 등)만의 고유 정보를 읽어야만 하는 UI가 있다면, 서버와 브라우저가 처음 렌더링하는 1차 스냅샷은 무조건 동일하게 통일(보통 비어있게)해주고, 그 즉시 **2차 리렌더링(클라이언트 전용)**을 촉발해서 브라우저 정보로 갈아치워라!

✅ 영호의 리팩토링: Mounted 상태 분리

// ✅ 우아한 코드 (Pro Approach)
'use client'
import { useState, useEffect } from 'react'
 
export default function ThemeGreeting() {
  // 1. 처음엔 무조건 '로딩 중' 혹은 '기본값' 으로 서버와 클라이언트가 합의를 본다.
  const [mounted, setMounted] = useState(false);
  const [theme, setTheme] = useState('light');
 
  // 2. useEffect는 서버사이드 렌더링 도중에는 절대 발동하지 않는다. 
  // 오직 브라우저에서 'Hydration' 이 끝난 직후 1회만 발동한다!
  useEffect(() => {
    setTheme(localStorage.getItem('theme') || 'light');
    setMounted(true); // "나 브라우저에 안전하게 착륙(Mount) 완료했어!"
  }, []);
 
  // 3. 서버와 클라이언트의 첫 1차 렌더링 스냅샷 시점. (둘 다 mounted = false) -> 껍데기 완벽 일치!
  if (!mounted) {
    return <div className="bg-white">스켈레톤 UI (합의된 빈 껍데기)</div>;
  }
 
  // 4. useEffect 발동 후 (2차 렌더링) -> 브라우저에서만 조용히 다크모드로 갈아끼워짐
  return (
    <div className={theme === 'dark' ? 'bg-black text-white' : 'bg-white text-black'}>
      안녕하세요, 영수네 커뮤니티입니다!
    </div>
  )
}

이 패턴의 아름다움:
서버가 렌더링한 초기 HTML과 클라이언트가 첫 렌더링하는 JSX 요소(mounted === false 상태)가 완벽하게 동일하기 때문에 리액트가 아무런 불평(에러) 없이 수화(Hydration)를 완료해. 안착이 성공한 직후 useEffect가 비로소 로컬 스토리지를 읽고 2차 렌더링으로 부드럽게 UI 교체 마술을 부리는 거야.

🌙 다크테마 mounted 패턴의 성능 트레이드오프와 베스트 프랙티스 🟡

🎯 이 섹션을 읽고 나면:

• mounted 패턴을 다크테마에 쓸 때 발생하는 성능 손해가 무엇인지 설명할 수 있다
• CSS 변수를 활용해 깜빡임 없는 다크테마를 구현하는 방법을 안다
• next-themes 라이브러리가 어떻게 이 문제를 해결하는지 이해한다

mounted 패턴의 숨겨진 비용

앞에서 배운 mounted 패턴은 작동은 완벽하지만, 다크테마에 적용하면 두 가지 비용이 따라와:

1. 추가 리렌더링 (Extra Render)
컴포넌트가 무조건 2번 렌더링돼. 첫 번째는 스켈레톤(흰 화면), 두 번째가 실제 테마 적용. 컴포넌트가 복잡할수록 이 비용이 커져.

2. 레이아웃 시프트 (Layout Shift)
첫 렌더(흰 배경) → 테마 적용(검은 배경)으로 바뀌는 순간 화면이 순간 반짝이는 현상이 생겨. 다크모드 유저라면 흰 화면이 0.1~0.2초 보였다가 사라지는 불쾌한 경험이야.

// mounted 패턴의 비용이 보이는 순간
if (!mounted) {
  return <div className="bg-white">스켈레톤</div>;  // 1차 렌더: 흰 화면 잠깐 보임
}
return <div className={theme === 'dark' ? 'bg-black' : 'bg-white'}>...</div>; // 2차 렌더

이게 "어쩔 수 없는 손해"일까? 아니야. CSS 변수를 활용하면 이 비용을 거의 없앨 수 있어.

베스트 프랙티스: CSS 변수 + suppressHydrationWarning

CSS 변수 방식은 HTML의 data-theme 속성 하나로 테마를 전환해. 자바스크립트가 개입하기도 전에, 인라인 스크립트가 localStorage에서 테마를 읽어 <html> 태그에 속성을 적용하거든.

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    // suppressHydrationWarning: html 태그의 data-theme 속성이
    // 서버/클라이언트 간 다르더라도 경고를 억제하겠다는 선언
    <html lang="ko" suppressHydrationWarning>
      <head>
        {/* 페이지 파싱 직후 즉시 실행되어 깜빡임 방지 */}
        <script dangerouslySetInnerHTML={{
          __html: `
            (function() {
              var theme = localStorage.getItem('theme') || 'light';
              document.documentElement.setAttribute('data-theme', theme);
            })();
          `
        }} />
      </head>
      <body>{children}</body>
    </html>
  )
}

/* globals.css — CSS 변수로 테마 전환 */
[data-theme='light'] {
  --bg-primary: #ffffff;
  --text-primary: #000000;
}
 
[data-theme='dark'] {
  --bg-primary: #1a1a1a;
  --text-primary: #ffffff;
}
 
body {
  background-color: var(--bg-primary);
  color: var(--text-primary);
}

이 방식에서는 컴포넌트 내부에서 useState(false) + useEffect 패턴이 필요 없어. CSS가 알아서 테마를 적용하기 때문이야.

next-themes 라이브러리가 이 모든 걸 해결해줘

실무에서는 이 복잡한 로직을 직접 구현하는 대신, next-themes 라이브러리를 많이 써. 내부적으로 CSS 변수 방식과 suppressHydrationWarning을 조합해서 깜빡임 없는 다크테마를 제공해.

// app/layout.tsx
import { ThemeProvider } from 'next-themes'
 
export default function RootLayout({ children }) {
  return (
    <html suppressHydrationWarning>
      <body>
        <ThemeProvider
          attribute="data-theme"    // HTML 속성으로 테마 관리
          defaultTheme="system"     // OS 다크모드 설정 따라감
          enableSystem              // 시스템 테마 감지 활성화
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

// 개별 컴포넌트에서 사용
'use client'
import { useTheme } from 'next-themes'
 
export function ThemeToggle() {
  const { theme, setTheme } = useTheme()
  return (
    <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
      {theme === 'dark' ? '☀️' : '🌙'}
    </button>
  )
}

⚠️ 주의: next-themes의 useTheme()도 내부적으로 마운트 여부를 확인해. mounted 상태가 false일 때 theme이 undefined로 나올 수 있으니 초기 아이콘을 그릴 때는 방어 처리가 필요해.

언제 어떤 방식을 써야 해?

💡 한 줄로 기억하기
mounted 패턴은 Hydration 에러를 막는 긴급처방이야. 실무 다크테마는 CSS 변수 + suppressHydrationWarning으로 깜빡임까지 해결해. next-themes를 쓰면 이 모든 복잡함을 라이브러리가 대신 처리해줘.

💥 에러 해결 카탈로그

에러 메시지가 뜨면 Ctrl+F로 검색해봐.

❌ window is not defined

원인: SSR 과정에서 즉시 실행되는 본문 레벨(Top level)에 브라우저 전용 객체를 선언해 읽었을 때.
해결책: useEffect 내부로 코드를 넣거나, typeof window !== 'undefined' 조건문으로 감싼다 (단 조건문 렌더링은 위에서 배운 Mismatch 에러를 유발할 수 있으므로 Mounted 패턴을 동시에 써야 한다).

❌ Expected server HTML to contain a matching <div> in <body> 혹은 <p> cannot appear as a descendant of <p>

원인: Hydration 에러의 변형. 서버에서는 문법이 맞았는데 브라우저가 읽어보니 비정상적인 HTML 트리라서 파서가 멋대로 DOM을 수정해버린 경우. 주로 <p> 태그 안에 <div> 같은 블록 태그를 넣었을 때 브라우저가 강제로 <p>를 닫아버리면서 서버 뷰 트리와 클라이언트 뷰 트리가 어긋남.
해결책: 웹 표준 문법을 철저히 지켜서 마크업한다. (inline 태그 안에 block 태그 금지 등)

🏁 이번에 배운 내용 총정리

💡 한 줄로 기억하기
클라이언트 컴포넌트(use client) 라 할지라도 1차 렌더링 단 한 번은 무조건 공장(서버) 에서 구워져서 온다. 서버와 브라우저가 보는 1차 그림은 어떤 수가 있어도 100% 같아야 한다. 브라우저만의 고유 정보는 수화(Hydrate) 완료를 확인받은 뒤, useEffect 타이밍부터 당당하게 읽어라!

🐣 영철이의 퇴근 일기

오늘은 정말 식은땀 흘리는 하루였어. 내 화면이 왜 찢어지는지(Mismatch) 드디어 알게 됐거든. 서버에서 온 빈대떡이랑 브라우저가 구운 빈대떡이 토핑이 다르면 리액트가 화를 낸다는 영호 리드 님 의 비유가 귀에 쏙 박히더라.

💡 오늘의 교훈: "서버와 클라이언트의 첫 만남은 언제나 100% 일치해야 한다! 브라우저 정보는 Hydration 이후에만 꺼내자."

typeof window !== 'undefined' 조건문만 믿고 안일하게 코딩했던 나 자신을 반성하며... 이제는 '마운트 보장 패턴' 을 내 주무기로 삼아야겠어. 그래도 에러를 잡고 나니 마음이 한결 가볍다! 오늘 운동 가서 땀 좀 쫙 빼고 스트레스 풀어야지. 내일은 리액트보다 더 날카로운 눈으로 코드를 지켜보겠어! 🐣

🔗 더 알아보기

• Next.js Docs: Rendering and Hydration