📚 hydration mismatch 대응 정리 - codesquad-masters2025-team01/issue-tracker GitHub Wiki

🤔 고민 상황

Next.js App Router에서 layout.tsx에 "use client"를 사용하지 않았음에도 hydration mismatch 에러가 발생함.

// src/app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="ko">
      <body>
        <ClientProviders>{children}</ClientProviders>
      </body>
    </html>
  );
}

📌 문제 원인 분석

에러메세지

Error: A tree hydrated but some attributes of the server rendered HTML didn't match the client properties...
  <body
    cz-shortcut-listen="true"
    style={{}}
  >

ColorZilla 확장 프로그램이 <body> 태그에 cz-shortcut-listen="true" 속성을 동적으로 추가
React DevOverlay 또는 Emotion이 클라이언트에서 빈 style={{}}을 삽입
이로 인해 서버에서 렌더링된 HTML과 클라이언트가 계산한 DOM이 일치하지 않아 hydration mismatch 경고 발생

📦 에러 해결과 관련된 유용한 개념

Hydration: SSR로 생성된 HTML을 React가 클라이언트에서 React 트리로 변환하는 과정
SSR vs CSR: 서버 컴포넌트는 Node.js에서 순수 HTML을, 클라이언트 컴포넌트는 브라우저에서 JS 렌더링
Dynamic 속성: 브라우저 확장이나 DevOverlay가 클라이언트에서만 삽입하는 속성
suppressHydrationWarning: React에서 특정 요소의 서버/클라이언트 DOM 차이를 무시하도록 하는 속성

✅ 해결 방법:

ColorZilla 확장 기능 사용 중지

브라우저 확장 관리자에서 ColorZilla를 비활성화
페이지 새로고침 후 <body>에 더 이상 cz-shortcut-listen="true" 속성이 붙지 않는지 확인
hydration mismatch 경고가 사라졌다면 해결 완료

<body suppressHydrationWarning> 속성 추가

// src/app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="ko">
      <body suppressHydrationWarning>
        <ClientProviders>{children}</ClientProviders>
      </body>
    </html>
  );
}

React가 <body>의 서버/클라이언트 속성 차이를 무시하여 hydration mismatch 경고 제거

⚠️ GitHub.com Fallback ⚠️