NextJS 15 App Router中如何在服务端渲染时应用MUI 6主题？

要解决服务端渲染阶段MUI使用默认主题、水合后切换自定义主题的样式闪烁问题，同时避免函数传递的序列化错误，按以下步骤操作：

1. 定义共享的纯静态主题配置 #

创建不含函数的纯主题配置文件，确保服务端和客户端能基于它生成完全一致的主题：

// src/theme/config.ts
export const baseThemeConfig = {
  palette: {
    primary: {
      main: '#1976d2', // 你的自定义主色
    },
    secondary: {
      main: '#dc004e', // 你的自定义次色
    },
    mode: 'light', // 或 'dark'
  },
  typography: {
    fontFamily: '"Inter", "Roboto", sans-serif',
    h1: {
      fontSize: '2.5rem',
      fontWeight: 700,
    },
  },
  // 仅保留纯对象配置，不要添加transform这类函数属性
};

2. 创建客户端Providers组件 #

在客户端组件中基于共享配置生成主题，同时包裹MUI的主题缓存与提供者组件：

// src/app/providers.tsx
'use client';

import { createTheme, ThemeProvider } from '@mui/material/styles';
import { AppRouterCacheProvider } from '@mui/material-nextjs/v13-appRouter';
import { baseThemeConfig } from '../theme/config';

// 客户端侧生成主题
const theme = createTheme(baseThemeConfig);

export default function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AppRouterCacheProvider>
      <ThemeProvider theme={theme}>
        {children}
      </ThemeProvider>
    </AppRouterCacheProvider>
  );
}

3. 在服务端RootLayout中集成Providers #

在默认的Server Component类型layout.tsx中，直接导入并使用客户端Providers组件：

// src/app/layout.tsx
import Providers from './providers';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="zh-CN">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

关键说明 #

• 服务端渲染主题生效的核心：AppRouterCacheProvider是MUI专为Next.js 13+ App Router设计的组件，它会自动处理服务端渲染时的样式收集与注入——当客户端组件在服务端渲染阶段执行时，MUI会基于生成的主题同步生成对应的CSS样式，嵌入到服务端输出的HTML中，确保首次加载就应用自定义主题，避免水合后的样式闪烁。
• 规避序列化错误的原因：通过服务端和客户端各自基于纯配置生成主题，避免了跨组件传递含函数的主题对象（createTheme返回的对象包含大量函数属性，无法被Next.js的Server Component序列化传递）。
• 若需主题包含函数逻辑：将函数（如自定义样式变换）仅定义在客户端组件中，或封装为可在服务端、客户端安全执行的纯函数，不要随主题配置跨组件传递。

内容的提问来源于stack exchange，提问作者Micah LaSala