Next.js의 하이드레이션 오류란 무엇인가요?

하이드레이션(hydration) 은 서버가 보낸 정적 HTML에, 클라이언트의 리액트가 이벤트 핸들러와 상태를 붙여 상호작용 가능하게 만드는 과정입니다.

하이드레이션 오류란

리액트는 하이드레이션 때 서버가 만든 HTML과 클라이언트의 첫 렌더 결과가 같다고 가정합니다. 둘이 다르면 “Hydration failed…” 경고가 나고, 해당 부분을 클라이언트 기준으로 다시 그립니다. 이를 하이드레이션 불일치(mismatch) 라고 합니다.

흔한 원인

서버와 클라이언트에서 다른 결과를 만드는 코드가 원인입니다.

• window·localStorage 등 브라우저 전용 API를 렌더링 중 사용
• Date.now(), Math.random() 처럼 매번 달라지는 값을 렌더에 사용
• typeof window !== 'undefined'로 서버/클라이언트 분기해 다른 마크업 출력
• <p> 안에 <div>를 넣는 등 잘못된 HTML 중첩(브라우저가 자동 교정)
• 브라우저 확장 프로그램이 DOM을 변형

해결 방법

• 브라우저 전용 로직은 useEffect 안에서 실행 (effect는 클라이언트에서만 동작)
• 클라이언트에서만 달라지는 값은 마운트 후 useState로 반영

'use client';
function Time() {
  const [now, setNow] = useState(null);
  useEffect(() => setNow(new Date().toLocaleTimeString()), []);
  return <span>{now ?? '로딩...'}</span>; // 서버/첫 렌더는 동일하게
}

• 정말 클라이언트에서만 그려야 하면 동적 임포트로 SSR을 끕니다: dynamic(() => import('./C'), { ssr: false })
• 올바른 HTML 중첩 규칙을 지킵니다.