NextJS集成Material UI出现Prop `className` did not match报错如何解决？

1. 排查自定义主题的服务端兼容性 #

检查你../src/themes下定义的defaultTheme代码，确认有没有直接用到window、navigator这类仅客户端存在的API，如果有，要添加环境判断逻辑区分服务端和客户端，避免服务端渲染时生成的主题配置和客户端不一致，导致类名计数偏差。

2. 固定JSS类名生成规则 #

自定义MUI的类名生成器，避免服务端和客户端计数不同步：
首先在_document.tsx中添加配置：

// 顶部新增导入
import { createGenerateClassName } from '@material-ui/core/styles';

// 调整getInitialProps中的sheets初始化逻辑
static getInitialProps = async (ctx: DocumentContext) => {
    const generateClassName = createGenerateClassName({
        productionPrefix: 'mui',
        seed: 'custom-fixed-seed', // 填写任意固定字符串即可
    });
    const sheets = new ServerStyleSheets({ generateClassName });
    // 剩下的原有逻辑保持不变
}

同时在_app.tsx中同步配置：

// 顶部新增导入
import { createGenerateClassName, StylesProvider } from '@material-ui/core/styles';

const generateClassName = createGenerateClassName({
    productionPrefix: 'mui',
    seed: 'custom-fixed-seed', // 和_document中配置的字符串完全一致
});

const MyApp: FC<AppProps> = ({ Component, pageProps }) => {
    // 原有逻辑保持不变
    return (
        <StylesProvider generateClassName={generateClassName}>
            {/* 原有Head、ThemeProvider等代码保持不变 */}
        </StylesProvider>
    )
}

3. 排查依赖冲突 #

检查package.json，确认没有同时安装@material-ui/core（MUI v4）和@mui/material（MUI v5）两个版本的依赖，版本混用会直接导致类名生成冲突，删除多余的版本即可。

4. 排查动态渲染逻辑 #

查看报错中指向的pages/index.tsx里的Home组件，确认有没有仅客户端才会渲染的内容，比如依赖useEffect才会更新的状态、仅在浏览器环境生效的条件判断，这类逻辑会导致服务端和客户端渲染的DOM结构不一致。如果有，可以用next/dynamic关闭这部分组件的服务端渲染：

import dynamic from 'next/dynamic';

const ClientOnlyComponent = dynamic(() => import('../components/YourComponent'), {
  ssr: false,
});

5. 开发环境特殊说明 #

如果仅在next dev启动的开发环境出现该警告，生产构建后运行无报错，属于NextJS开发环境热更新、严格模式导致的常见副作用，不影响线上使用，可以直接忽略，也可以临时关闭严格模式验证问题：

// next.config.js
module.exports = {
  reactStrictMode: false,
}

内容的提问来源于stack exchange，提问作者tavin-dev