Material-UI 在 Next.js App Router 中的 ClassName 生成器问题解析

2025-04-29 11:36:25作者：蔡丛锟

问题背景

在使用 Material-UI 与 Next.js 的 App Router 架构结合时，开发者遇到了一个关于 ClassName 生成器的配置问题。Material-UI 提供了一个实验性的 ClassNameGenerator API，用于自定义生成的 CSS 类名前缀，但在 Next.js 的 App Router 模式下，这一功能出现了异常。

核心问题表现

在 Next.js App Router 架构下，按照官方文档配置 ClassNameGenerator 后，类名前缀未能生效
当尝试将配置脚本放在 layout.tsx 中时，由于 Next.js 的服务器组件特性，配置无法正常工作
即使通过变通方法使部分功能工作，仍存在服务器端和客户端渲染不一致的问题，导致 hydration 错误

技术原理分析

Material-UI 的 ClassNameGenerator 是一个全局配置工具，需要在应用的最早期初始化。在传统的客户端渲染或 Pages Router 架构中，这通常通过在应用的入口文件（如 _app.tsx）中导入配置脚本即可实现。

然而，Next.js 的 App Router 引入了服务器组件概念，带来了几个关键变化：

默认情况下，所有组件都是服务器组件
服务器组件无法使用客户端特有的 API 和状态
布局文件(layout.tsx)默认是服务器组件

解决方案探索

经过社区讨论和核心团队验证，目前可行的解决方案包括：

配置脚本改造：必须确保 ClassNameGenerator 配置脚本被标记为客户端组件，在文件顶部添加 'use client' 指令
导入位置调整：由于 Next.js 当前版本存在客户端模块过滤的 bug，需要在配置脚本中导出内容并在布局中显式导入
页面级导入：作为临时解决方案，可以在每个页面文件中导入配置脚本，但这会带来维护负担

最佳实践建议

基于当前技术限制，推荐以下实现方案：

创建独立的初始化文件 initialize-mui.ts，内容如下：

'use client';
import { unstable_ClassNameGenerator as ClassNameGenerator } from '@mui/material/className';

ClassNameGenerator.configure((componentName) => `test-${componentName}`);

export default null;

在布局文件中导入并使用：

import MuiInitializer from './initialize-mui';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <MuiInitializer />
        {children}
      </body>
    </html>
  );
}