Next.js에서 Hydration 오류 수정

Source: Dev.to

하이드레이션 오류의 일반적인 원인

브라우저/환경 문제

• 브라우저 확장 프로그램이 속성을 주입 (비밀번호 관리자, 광고 차단기, 접근성 도구 등)
• 브라우저 자동 완성이 폼 요소에 속성을 추가
• React가 하이드레이션하기 전에 서드파티 스크립트가 DOM을 수정
• 서버와 클라이언트 간의 시간대 차이로 인해 날짜/시간 불일치 발생

코드 문제

• SSR 중에 브라우저 전용 API(window, localStorage, document) 사용
• 렌더 단계에서 무작위 값이나 Math.random() 사용(서버와 클라이언트가 다른 값을 생성)
• new Date()를 사용하면서 일관된 포맷이 없는 경우
• 초기 렌더 시 내용을 변경하는 useEffect 또는 useState 사용
• 템플릿 리터럴 내 공백 불일치(여분의 공백, 줄바꿈 등)
• 클라이언트 전용 값(window.innerWidth, 사용자 에이전트 감지) 기반 조건부 렌더링

데이터 문제

• 서버와 클라이언트가 서로 다른 데이터 또는 서로 다른 시점에 데이터를 가져옴
• 리스트에서 key prop 누락으로 인한 순서 재배열 문제
• 서버 컴포넌트에서 직렬화 불가능한 데이터(함수, Symbol 등) 사용
• 서버와 클라이언트 간 데이터 포맷 불일치(날짜, 숫자, 로케일 등)

CSS/스타일링 문제

• 서버와 클라이언트에서 서로 다른 클래스명을 생성하는 CSS‑in‑JS 라이브러리
• 해시 생성이 일관되지 않은 CSS 모듈
• 서버와 클라이언트에서 다른 스타일을 적용하는 미디어 쿼리

컴포넌트 문제

• 인라인 요소 안에 블록 요소를 중첩

  <span>
    <div>inside</div>
  </span>

• 잘못된 HTML 구조(SSR이 브라우저가 파싱하는 방식과 다르게 렌더링될 수 있음)

• SSR 호환되지 않는 서드파티 컴포넌트

• 포털이 다른 위치에 렌더링되는 경우

모범 사례

코드가 클라이언트 전용 API에 의존하는지 항상 확인하고, 필요하면 useEffect로 감싸거나 'use client' 지시자를 적절히 사용하세요.