使用Material UI v5搭配Next.js v11出现className不匹配报错如何解决？

排查与解决步骤 #

• 第一步：确认src/createEmotionCache.js配置正确
  该文件是最常见的出错点，需保证服务端和客户端使用统一的emotion缓存key，参考正确配置：

import createCache from '@emotion/cache';

export default function createEmotionCache() {
  // key必须固定为css，和MUI官方配置一致
  return createCache({ key: 'css', prepend: true });
}

• 第二步：检查是否存在服务端与客户端渲染内容不一致的情况
  排查项目中所有组件：

  1. 不要在渲染逻辑中直接使用window、document等客户端独有API，如需使用请放在useEffect回调中执行
  2. 不要在渲染逻辑中使用随机数、当前时间等服务端和客户端生成结果不一致的变量，避免绑定到className、id等属性上
  3. 检查是否存在条件渲染逻辑仅在客户端触发，导致服务端和客户端输出的DOM结构不一致

• 第三步：检查依赖与编译配置

  1. 确认package.json中不存在v4版本的@material-ui/*依赖，避免和v5版本的@mui/*依赖冲突导致类名生成规则混乱，如有重复请卸载旧版本依赖后重新安装
  2. 在next.config.js中开启emotion编译支持，同时可临时关闭严格模式排查冲突：

  module.exports = {
    reactStrictMode: false,
    compiler: {
      emotion: true
    }
  }
  

• 第四步：验证生产环境表现
  如果仅开发环境出现该警告，生产环境执行next build && next start后无警告，属于开发环境Fast Refresh和emotion缓存的兼容问题，不影响线上功能，可通过升级Next.js到12+版本彻底解决。

内容的提问来源于stack exchange，提问作者Shaban Akhtar