解决Next.js+Material-UI主题切换时的Hydration错误

问题背景 #

开发Next.js项目时，基于MUIv5实现主题切换功能，已完成配色、字体切换逻辑，并用Cookie持久化选中的主题（因Next.js首渲染不支持localStorage）。但切换主题后刷新页面，触发Hydration错误，提示：Text content does not match server-rendered HTML。尝试给整个应用添加"use Client"标记后问题仍未解决。

核心原因 #

服务端渲染阶段无法读取客户端Cookie，导致服务端输出的页面使用默认主题（"Default"），而客户端Hydration时从Cookie读取到已选中的自定义主题，两者DOM内容（如下拉框选中值）不一致，触发Next.js的Hydration校验错误。即使添加"use Client"，Hydration阶段仍要求客户端初始状态与服务端输出的HTML完全匹配，直接在useState中读取Cookie会导致状态不匹配。

修复方案 #

方案1：服务端获取Cookie传递初始值（推荐） #

在_app.js中通过getInitialProps（或getServerSideProps）在服务端读取Cookie，将选中的主题名作为props传递给组件，确保服务端与客户端初始状态完全一致。

修改_app.js代码：

import App from 'next/app';
import cookie from 'cookie';
import { useState } from 'react';
// 导入你的theme、theme1等主题对象

function MyApp({ Component, pageProps, initialThemeName }) {
  const themesArr = [
    { name: "Default", themeName: theme },
    { name: "Green", themeName: theme1 },
    // 其他主题配置...
  ];

  const [selectedThemeName, setSelectedThemeName] = useState(initialThemeName);
  const [selectedTheme, setSelectedTheme] = useState(
    themesArr.find(t => t.name === selectedThemeName).themeName
  );

  const handleChange = (event) => {
    const newThemeName = event.target.value;
    setSelectedThemeName(newThemeName);
    setSelectedTheme(themesArr.find(t => t.name === newThemeName).themeName);
    cookie.set("selectedThemeName", newThemeName, { expires: 365 });
  };

  return (
    // 应用根组件内容，包含Select组件
    <div>
      <Select
        sx={{
          backgroundColor: "primary.main",
          color: "common.white",
          maxWidth: "90px",
        }}
        autoWidth
        value={selectedThemeName}
        onChange={handleChange}
      >
        {themesArr.map((theme) => (
          <MenuItem key={theme.name} value={theme.name}>
            {theme.name}
          </MenuItem>
        ))}
      </Select>
      <Component {...pageProps} />
    </div>
  );
}

MyApp.getInitialProps = async ({ ctx }) => {
  // 服务端读取请求头中的Cookie
  const cookies = cookie.parse(ctx.req ? ctx.req.headers.cookie || '' : document.cookie);
  const initialThemeName = cookies.selectedThemeName || "Default";
  
  return { initialThemeName };
};

export default MyApp;

方案2：延迟客户端状态初始化（快速适配） #

若不想修改服务端逻辑，可通过useEffect在Hydration完成后再读取Cookie更新状态，避免初始状态与服务端输出不匹配。

修改状态处理代码：

import { useState, useEffect } from 'react';
import cookie from 'cookie';
// 导入你的theme、theme1等主题对象

const themesArr = [
  { name: "Default", themeName: theme },
  { name: "Green", themeName: theme1 },
  // 其他主题配置...
];

// 初始状态使用服务端渲染的默认值
const [selectedThemeName, setSelectedThemeName] = useState("Default");
const [selectedTheme, setSelectedTheme] = useState(theme);

useEffect(() => {
  // Hydration完成后读取Cookie更新状态
  const savedThemeName = cookie.get("selectedThemeName") || "Default";
  setSelectedThemeName(savedThemeName);
  setSelectedTheme(themesArr.find(t => t.name === savedThemeName).themeName);
}, []);

const handleChange = (event) => {
  const newThemeName = event.target.value;
  setSelectedThemeName(newThemeName);
  setSelectedTheme(themesArr.find(t => t.name === newThemeName).themeName);
  cookie.set("selectedThemeName", newThemeName, { expires: 365 });
};

额外注意事项 #

• 确保MUI的ThemeProvider使用客户端状态中的selectedTheme，避免服务端与客户端主题样式不匹配。
• 若使用Next.js 13+ App Router，需将主题相关逻辑放在Client Component中，并通过Server Component读取Cookie传递props（App Router中Server Component可直接读取请求头Cookie）。

内容的提问来源于stack exchange，提问作者Zaid Shaikh