Next.js 개발 중 Hydration Error와 원인 분석

이 게시물은 Next.js SSR 환경에서 자주 발생하는 Hydration Error의 원인과 해결 방법에 대해 설명합니다.

Hydration Error란?

• 서버에서 렌더된 HTML과 클라이언트 렌더링 결과가 다를 때 발생하는 오류
• 서버와 클라이언트의 실행 환경 차이(날짜, 랜덤 값, 브라우저 API 등)로 인해 발생 가능

주요 원인 및 해결책

• 브라우저 API를 SSR에서 사용하지 않도록 주의
• 날짜, 시간, 랜덤 값은 CSR에서만 처리하거나 SSR과 클라이언트의 값 일치를 보장
• 상태 관리 초기값의 일관성 유지
• 필요 시 dynamic import로 CSR 전용 컴포넌트 처리

실제 사례: dayjs locale 차이 문제

• 서버는 기본 locale이 en-US, 클라이언트는 ko-KR로 달라 포맷 결과가 다름
• 이로 인해 Hydration Error가 발생했으며, 서버 locale 명시적 설정이 필요함

결론

Hydration Error는 데이터 불일치가 핵심 원인이며, SSR과 CSR 간 환경 차이를 꼼꼼히 점검하는 것이 중요함을 강조합니다.