🔥 Trouble Shooting - Next.js 다크모드 구현 중 발생한 하이드레이션 오류..

슘·2025년 3월 14일

CSR SSR TROUBLESHOOTING darkMode hydration next-themes next.js suppressHydrationWarning 다크모드 하이드레이션 오류

🔥 Trouble Shooting

목록 보기

13/23

👀 문제 상황

Next.js에서 next-themes 라이브러리를 사용하여 다크모드 기능을 구현하는 중 다음과 같은 오류 메시지가 콘솔에 나타났다:

hook.js:608 Warning: Extra attributes from the server: class,style 
Error Component Stack
    at html ()
    at RootLayout [Server] ()

이 오류는 서버 사이드 렌더링(SSR)과 클라이언트 사이드 렌더링(CSR) 사이에 불일치가 발생했기 때문에 나타난다. 주로 next-themes와 같이 클라이언트 측에서 동작하는 라이브러리가 서버에서 렌더링된 HTML과 클라이언트에서 하이드레이션 후의 DOM을 비교할 때 차이가 있을 경우 발생한다.

🔍 Next.js의 렌더링 과정과 하이드레이션 불일치 문제

🛜 서버 측 렌더링 (SSR) 단계

사용자가 웹페이지를 요청하면, Next.js는 서버에서 React 컴포넌트를 실행함
이때 next-themes와 같은 클라이언트 측 라이브러리는 아직 완전히 작동하지 않은 상태
서버는 theme 값을 알 수 없거나 기본값만 알고 있음(예: 'light').
따라서 서버는 이 기본값 기준으로 HTML을 생성(예: 라이트 모드 버튼 UI).
생성된 HTML이 사용자의 브라우저로 전송된 상태

👩‍💻 클라이언트 측 하이드레이션 단계

브라우저가 HTML을 받으면, React가 "하이드레이션" 과정을 시작
하이드레이션 중에 next-themes 라이브러리가 초기화되고 실제 테마 값 확인
이때 로컬 스토리지에 저장된 사용자의 테마 설정(예: 'dark')이 있다면 그것을 로드
React는 이 실제 테마 값을 기반으로 DOM을 업데이트하려고 함

⚠️ 불일치 발생

여기서 문제가 발생:

서버는 기본 테마(예: 'light')로 HTML을 생성
클라이언트는 실제 사용자 설정(예: 'dark')에 따라 DOM을 업데이트하려 시도
React는 서버에서 생성한 HTML과 클라이언트에서 렌더링하려는 결과가 다르다는 것을 감지
이 차이가 "하이드레이션 불일치" 경고를 발생시키고 있음!

🧩 문제의 코드

문제가 발생한 코드는 다음과 같다:

"use client";
import { useTheme } from "next-themes";
import React, { useEffect, useState } from "react";
import { IoMoon } from "react-icons/io5";
import { FaSun } from "react-icons/fa";
import cn from "clsx";

const ThemeChange = () => {
  const DEFAULT_BUTTON_WRAPPER = "right-4 bottom-4 rounded-4xl w-[48px] h-[48px] fixed hover:scale-120 transition-all cursor-pointer";
  const DEFAULT_ICON_STYLE = "my-0 mx-auto trans absolute top-1/2 left-1/2 transform -translate-x-1/2 -translate-y-1/2";
  const { theme, setTheme } = useTheme();
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  if (!mounted) return null;

  return (
    <>
      {theme !== "dark" ? (
        <div onClick={() => setTheme("dark")} className={cn(DEFAULT_BUTTON_WRAPPER, "bg-blue-950")}>
          <IoMoon className={cn(DEFAULT_ICON_STYLE, "text-gray-100")} />
        </div>
      ) : (
        <div onClick={() => setTheme("light")} className={cn(DEFAULT_BUTTON_WRAPPER, "bg-blue-300")}>
          <FaSun className={cn(DEFAULT_ICON_STYLE, "text-yellow-500")} />
        </div>
      )}
    </>
  );
};

export default ThemeChange;

🤔 원인 분석

이 오류의 주요 원인은 다음과 같다:

하이드레이션 불일치: 서버에서는 theme 값을 알 수 없기 때문에 기본값으로 렌더링하고, 클라이언트에서는 실제 테마 값을 적용하여 렌더링한다. 이로 인해 두 렌더링 결과가 달라진다.

💡 해결 과정

첫째로, 일반적인 방식인 mounted 상태를 도입하여 컴포넌트가 클라이언트에 마운트된 후에만 렌더링되도록 했다. 하지만 이것만으로는 문제가 해결되지 않았다.
캐시 문제인지 확인하기 위해 강력 새로고침도 시도해 보았지만, 오류는 계속 발생했다.
다양한 방법을 찾아보던 중 suppressHydrationWarning 속성을 발견했다. 이 속성은 React에서 특정 요소의 하이드레이션 불일치 경고를 무시하도록 지시한다.

✅ 최종 해결책

div 요소에 suppressHydrationWarning 속성을 추가하여 문제를 해결했다:

  return (
    <html lang="en" suppressHydrationWarning> // 속성 추가
      <body
        className={`${geistSans.variable} ${geistMono.variable} antialiased bg-[#5b5f5e] relative`}
      >
        ...
      </body>
    </html>

이 속성을 추가한 후에는 하이드레이션 경고가 더 이상 나타나지 않았고, 다크모드 기능이 정상적으로 작동하게 되었다.

📚 교훈

이 트러블슈팅을 통해 배운 점은 다음과 같다:

SSR과 CSR의 차이점 이해: Next.js에서 서버 렌더링과 클라이언트 렌더링 사이의 차이점을 명확히 이해해야 한다.
하이드레이션 과정의 중요성: React의 하이드레이션 과정에서 발생할 수 있는 불일치를 예방하고 해결하는 방법을 알아야 한다.
테마 관련 라이브러리 사용 시 주의점: next-themes와 같은 클라이언트 측 상태에 의존하는 라이브러리를 사용할 때는 SSR과의 호환성을 고려해야 한다.
React의 특수 속성 활용: suppressHydrationWarning과 같은 React의 특수 속성이 문제 해결에 도움이 될 수 있다는 점을 알게 되었다.