Next.js使用next-themes切换主题时Image组件src不匹配警告及初始显示异常问题

我来帮你解决这个问题！你遇到的是Next.js SSR（服务端渲染）场景下，next-themes主题状态和Image组件服务端/客户端渲染不一致的典型问题，咱们一步步拆解原因并给出解决方案：

问题根源 #

Next.js在服务端渲染页面时，没办法获取到客户端的主题状态（比如用户本地存储的偏好主题），所以服务端会按照theme的初始默认值渲染对应的图标（也就是你的else分支sun）；但当客户端完成hydrate（注水）后，useTheme会正确获取到当前的主题状态（比如light），此时要渲染moon图标，这就导致了服务端和客户端输出的src属性不匹配，从而出现警告，同时初始会先显示服务端渲染的sun，再切换到客户端的目标图标，和预期不符。

解决方案一：等待客户端挂载后再渲染图标 #

通过React的useEffect和状态标记，让组件在客户端完全挂载后再渲染Image，避免服务端渲染出不匹配的内容：

"use client";

import moon from "public/icons/moon.svg";
import sun from "public/icons/sun.svg";
import Image from "next/image";
import { useTheme } from "next-themes";
import { useEffect, useState } from "react";

function ToggleDarkMode({ className }) {
  const { theme, setTheme } = useTheme();
  const [isClientMounted, setIsClientMounted] = useState(false);

  // 仅在客户端挂载完成后更新状态
  useEffect(() => {
    setIsClientMounted(true);
  }, []);

  // 服务端渲染时返回一个和图标尺寸一致的占位容器，避免布局偏移
  if (!isClientMounted) {
    return <div className={className} style={{ width: 24, height: 24 }} />;
  }

  return (
    <Image
      src={theme === "light" ? moon : sun}
      alt="moon or sun image"
      width={24}
      height={24}
    />
  );
}

export default ToggleDarkMode;

这个方案的核心是：服务端只渲染一个占位元素，不输出具体的图标路径；等客户端挂载后，再根据真实的主题状态渲染对应的Image，从根源上消除服务端和客户端的src不匹配问题。

解决方案二：动态导入组件并关闭SSR #

如果你的主题切换组件不需要在服务端渲染，可以用Next.js的dynamic导入，强制组件仅在客户端渲染：

首先修改父组件的导入逻辑：

// 父组件中导入ToggleDarkMode
import dynamic from 'next/dynamic';

const ToggleDarkMode = dynamic(() => import('./ToggleDarkMode'), {
  ssr: false,
  // 加载时显示占位，保持布局稳定
  loading: () => <div style={{ width: 24, height: 24 }} />
});

原ToggleDarkMode组件可以保持不变（依然保留"use client"指令）。这种方式下，服务端不会处理这个组件的渲染，完全交给客户端，自然就不会出现服务端和客户端的内容不匹配警告，初始显示也会直接根据客户端主题状态渲染正确的图标。

备注：内容来源于stack exchange，提问作者Hossein Rezaei