본문 바로가기
Q&A해결2026년 4월 28일1분 읽기

Next.js 16에서 갑자기 Hydration mismatch 에러가 폭증합니다

리
리액트초보
조회 755댓글 2

Next.js 15에서 16으로 올렸더니 갑자기 hydration mismatch 에러가 여기저기서 터집니다. 특히 new Date().toLocaleString() 쓰는 부분에서 다 터지는데, 15에서는 멀쩡했거든요.

이게 16의 변경 때문인가요? 아니면 원래 잘못된 코드였는데 16에서 더 엄격하게 잡는 건가요?

// 에러 나는 컴포넌트
'use client'
export default function Timestamp({ date }: { date: Date }) {
  return <time>{date.toLocaleString('ko-KR')}</time>
}

댓글 2

김김영삼6개월 전

16에서 더 엄격해졌습니다. 정확히는 React 19.2에서 hydration mismatch 검출 로직이 정교해졌고, Next.js 16이 이를 그대로 노출합니다. 이전엔 조용히 넘어가던 케이스가 이제 경고로 잡힙니다.


원인 — 서버와 클라이언트의 locale



  • 서버는 UTC(또는 en-US)로 toLocaleString 결과 생성

  • 클라이언트(한국 사용자)는 Asia/Seoul + ko-KR로 다시 생성

  • 두 결과가 다르므로 hydration mismatch


해결책 — 3가지 중 선택


1) ISO 문자열로 서버에서 보내고 클라이언트에서만 포맷


'use client'
import { useEffect, useState } from 'react'

export default function Timestamp({ iso }: { iso: string }) {
const [text, setText] = useState(iso) // SSR에서는 ISO 그대로
useEffect(() => {
setText(new Date(iso).toLocaleString('ko-KR'))
}, [iso])
return <time dateTime={iso}>{text}</time>
}

2) suppressHydrationWarning (간단하지만 마지막 수단)


<time suppressHydrationWarning>{date.toLocaleString('ko-KR')}</time>

3) 서버에서도 같은 timezone 강제


// next.config.js
module.exports = {
env: { TZ: 'Asia/Seoul' },
}
// 그리고 서버·클라이언트 모두 같은 옵션으로 포맷
new Intl.DateTimeFormat('ko-KR', {
timeZone: 'Asia/Seoul',
dateStyle: 'medium',
timeStyle: 'short',
}).format(date)

1번을 권장합니다. SEO 측면에서 ISO 문자열이 <time dateTime>으로 들어가고, 사용자에게는 로컬 시간으로 보입니다. 구글이 가장 정확히 이해하는 방식이에요.

리리액트초보(guest)6개월 전
1번 방식으로 수정하니 깔끔하게 해결됐습니다. useEffect로 클라이언트에서만 다시 포맷하는 패턴, 다른 곳에도 응용할게요. 감사합니다!
Ctrl+Enter로 등록