Material UI 官方示例工程与脚手架全解：Next.js、Vite、Remix 等集成样板的选型与运行指南

本文基于 Material UI 仓库中「Example projects」官方文档（example-projects.md）展开，完整覆盖官方集成示例清单、选型建议、各样板的工程结构与运行方式，并结合 examples/ 目录下的真实源码（主题配置、Emotion 缓存、Pigment CSS 入口等）深入讲解每个样板的关键实现，帮助读者跳过初始化步骤，快速搭起一个可运行的 Material UI 项目。

一、示例集合的定位与存放位置

Material UI 官方文档将「Example projects」定义为：一套将 Material UI 与主流库、框架预集成的示例与脚手架（scaffolds）合集。其核心价值在于：这些示例已经完成依赖安装、样式引擎配置、主题搭建等繁琐的初始设置，开发者可以“跳过初始配置步骤，直接进入业务开发”。

这些示例统一存放在仓库根目录的 examples 文件夹下，每个框架/工具组合对应一个独立子目录：

示例（文档页展示名）	仓库目录	语言版本	适用场景
Next.js App Router	examples/material-ui-nextjs / material-ui-nextjs-ts	JS + TS	服务端渲染、Next.js App Router
Next.js Pages Router	examples/material-ui-nextjs-pages-router / material-ui-nextjs-pages-router-ts	JS + TS	服务端渲染、Next.js Pages Router
Vite.js	examples/material-ui-vite / material-ui-vite-ts	JS + TS	轻量单页应用（SPA）
Remix	examples/material-ui-remix-ts	TS	Remix 全栈框架
Tailwind CSS + Vite	examples/material-ui-vite-tailwind-ts	TS	Material UI 与 Tailwind 混用
Preact	examples/material-ui-preact	JS	以 Preact 替代 React 的轻量方案
CDN	examples/material-ui-via-cdn	JS	无构建工具的原型验证
Express.js (server-rendered)	examples/material-ui-express-ssr	JS	自建 Express 服务端渲染
Gatsby	examples/material-ui-gatsby	JS	Gatsby 静态站点

上述清单与文档页渲染逻辑一一对应：官方文档页通过 MaterialUIExampleCollection 组件以卡片形式展示这 9 个示例，每个卡片提供 JavaScript / TypeScript 两种入口链接（Remix 与 Tailwind 组合仅提供 TypeScript 版本）。

此外，从 examples/ 目录结构看，仓库还维护了若干文档页未直接列出的配套样板，可按需取用：

• examples/material-ui-react-router-ts：基于 React Router v7 的 TypeScript 样板；
• examples/material-ui-nextjs-ts-v4-v5-migration：面向 Material UI v4 → v5 迁移场景的 Pages Router 参考工程（含 types/mui-styles.d.ts 类型声明）；
• examples/material-ui-pigment-css-vite-ts 与 examples/material-ui-pigment-css-nextjs-ts：实验性样式引擎 Pigment CSS 的 Vite / Next.js 样板。

二、官方选型建议

官方文档页给出了明确的选型指引：

• 需要服务端渲染（SSR）或更“有主见”（opinionated）的框架特性时，选择 Next.js；
• 构建轻量单页应用（SPA）时，选择 Vite；
• 对 React 应用创建方式有更多疑问时，可参考 React 官方文档的 “Creating a React App” 一节了解各方案差异。

这一建议与各示例的 README 内容互相印证：Next.js 两个样板（App Router / Pages Router）与 Express SSR 样板覆盖服务端渲染场景，Vite 系列样板则面向纯客户端 SPA。

三、示例的获取与运行方式

所有示例的获取流程一致（以 material-ui-vite/README.md 为准）：

1. 克隆 Material UI 仓库，或下载对应的发行包归档；
2. 从归档中解压出目标示例目录，例如：

# 下载仓库归档后，解压出 examples 下对应的示例目录，再进入该目录
cd material-ui-vite

3. 安装依赖并启动开发服务器：

npm install
npm run dev

4. 打开 http://localhost:3000（Next.js 类样板）或 http://localhost:5173（Vite 类样板）查看效果。

需要说明的例外：

• Preact 示例启动命令是 npm run start 而非 npm run dev（见 material-ui-preact/README.md），因为它基于 Create React App 构建；
• Express SSR 示例同样使用 npm run start 启动 Node 服务器；
• CDN 示例无需 npm install，直接以浏览器打开 index.html 即可（详见下文）。

四、各示例关键实现解析

4.1 Next.js App Router 样板：主题、字体与 CSS 变量

examples/material-ui-nextjs 是由 create-next-app 引导、并预装 Material UI 的 Next.js 项目。其主题文件 src/theme.js 展示了当前推荐的三个配置要点：

'use client';
import { Roboto } from 'next/font/google';
import { createTheme } from '@mui/material/styles';

const roboto = Roboto({
  weight: ['300', '400', '500', '700'],
  subsets: ['latin'],
  display: 'swap',
});

const theme = createTheme({
  cssVariables: true, // 启用 CSS 变量输出，样式运行时可通过变量覆盖
  palette: {
    mode: 'light',
  },
  typography: {
    fontFamily: roboto.style.fontFamily, // 使用 next/font 自托管的 Roboto
  },
  components: {
    MuiAlert: {
      styleOverrides: {
        root: {
          variants: [
            {
              props: { severity: 'info' },
              style: { backgroundColor: '#60a5fa' },
            },
          ],
        },
      },
    },
  },
});

export default theme;

从源码可以看到几处值得注意的工程实践：

• cssVariables: true 启用 CSS 变量模式，Material UI 样式以变量形式输出，便于在运行时切换主题或做局部覆盖；
• 字体不再依赖 public 下的静态文件，而是通过 next/font/google 自托管，并设置 display: 'swap' 做字体交换，兼顾首屏渲染体验；
• components.MuiAlert.styleOverrides.root.variants 使用了 slot-based 的 variants API，对 severity: 'info' 的 Alert 做单点覆盖，演示了 v7 版本组件级定制的标准写法。

TypeScript 版本 examples/material-ui-nextjs-ts 结构相同，且额外提供了 ModeSwitch.tsx 明暗模式切换组件。

4.2 Express SSR 样板：Emotion 缓存与样式注入点

examples/material-ui-express-ssr 是官方「Server Rendering」指南的参考实现（见其 README.md）。SSR 场景下，服务端渲染出的样式需要在客户端 hydration 时正确接管，否则会出现样式闪烁或重复注入。该样板的 createEmotionCache.js 给出了官方解法：

import createCache from '@emotion/cache';

const isBrowser = typeof document !== 'undefined';

// On the client side, Create a meta tag at the top of the <head> and set it as insertionPoint.
// This assures that Material UI styles are loaded first.
// It allows developers to easily override Material UI styles with other styling solutions, like CSS modules.
export default function createEmotionCache() {
  let insertionPoint;

  if (isBrowser) {
    const emotionInsertionPoint = document.querySelector('meta[name="emotion-insertion-point"]');
    insertionPoint = emotionInsertionPoint ?? undefined;
  }

  return createCache({ key: 'mui-style', insertionPoint });
}

从源码逻辑看，这个缓存做了两件事：

1. 客户端侧以 <head> 顶部的 <meta name="emotion-insertion-point"> 标签作为 Emotion 的 insertionPoint，保证 Material UI 样式最先被注入，从而可以被 CSS Modules 等其他样式方案自然覆盖；
2. 使用固定的 key: 'mui-style' 命名样式作用域，避免与其他 Emotion 缓存冲突。

配合样板中的 server.js、client.js 与 theme.js，即可完整复现 SSR + hydration 的全链路。

4.3 Vite 系列样板：JS、TS 与 Tailwind 混用

基础 Vite 样板 examples/material-ui-vite（及 TS 版 material-ui-vite-ts）包含 @mui/material 及其 peer dependencies，默认样式引擎为 Emotion。目录结构简单：src/App.jsx、src/main.jsx 与 src/theme.js 构成最小可运行骨架。

Tailwind 混用样板 examples/material-ui-vite-tailwind-ts 演示了 Tailwind CSS 与 Material UI 共存的方式：在 vite.config.ts 中通过 @tailwindcss/vite 插件接入 Tailwind，业务代码（如 src/PopoverMenu.tsx）中两种工具类/组件化写法可自由搭配。README 中同时注明：若偏好 styled-components，可参考官方 interoperability 文档替换样式引擎。

4.4 Remix 样板：全栈框架下的 SSR 集成

examples/material-ui-remix-ts 使用 Remix 全栈框架 + TypeScript。从目录结构看，样板完整实现了 Remix 的三层入口：entry.client.tsx / entry.server.tsx 分别处理客户端水合与服务端渲染，ClientStyleContext.tsx 与 createEmotionCache.ts 则沿用与 Express 样板一致的 Emotion 缓存策略，保证样式在 SSR/CSR 两侧行为一致。

4.5 Preact 样板：用 3 kB 的 React 替代方案跑 Material UI

examples/material-ui-preact 的 README 说明：Preact 是 API 与现代 React 一致的轻量（3 kB）替代方案，该样板使用 CRA + react-app-rewired 通过 config-overrides.js 为 webpack 添加 Preact 别名，从而让 @mui/material 的 React 依赖指向 Preact 运行时。运行命令为 npm run start。

4.6 CDN 样板：零构建的原型验证（及其局限）

examples/material-ui-via-cdn 展示了不引入任何前端构建基础设施直接使用 Material UI 的方式，基于 ESM CDN（esm.sh）加载依赖：

# React 19 或更高版本
open index.html
# React 18
open react-18-example.html

README 明确给出了官方立场：这种方式非常适合原型验证，但不建议用于生产环境——原因是客户端必须下载完整库，无论实际用到了哪些组件，都会影响性能与带宽。

4.7 Pigment CSS 实验样板

examples/material-ui-pigment-css-vite-ts 与 material-ui-pigment-css-nextjs-ts 将样式引擎从 Emotion 替换为实验性的 Pigment CSS。以 Vite 版入口 src/main.tsx 为例，接入方式只有两处差异：

import '@mui/material-pigment-css/styles.css'; // 引入 Pigment CSS 基础样式

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

结合 material-ui-pigment-css.d.ts 中的模块声明，可知该样板同时处理了 @mui/material-pigment-css 子路径的 TS 类型问题，可作为评估该实验性引擎的起点。

五、从示例到成品：免费模板与高级主题

官方文档在示例清单之后给出了两级进阶路径：

1. 免费模板（Free templates）：选定脚手架后，可安装官方现成的用户界面模板以更快起步，模板文档位于 docs/data/material/getting-started/templates 目录；
2. 高级主题与模板（Premium themes and templates）：对于更复杂的预构建 UI，官方指向 MUI Store 中的付费主题与模板（仓库内 docs/data/premium-themes 存放了对应的展示文档数据）。

六、小结

Material UI 的示例工程体系以 examples 目录为唯一事实来源，官方文档页（本文所依据的 example-projects.md）仅承担导航与选型建议职责，具体配置细节需以各示例自带 README 为准。落地建议可以归纳为：

• SSR / 全栈场景：优先 material-ui-nextjs（App Router，含 cssVariables 主题与 next/font 字体方案）；
• SPA 场景：优先 material-ui-vite，需要 Tailwind 混用时切到 material-ui-vite-tailwind-ts；
• 自建 Node 服务器做 SSR：以 material-ui-express-ssr 为参考实现，重点关注其 Emotion insertionPoint 策略；
• 零构建原型：使用 material-ui-via-cdn，但生产环境不建议沿用；
• 探索新样式引擎：从两个 Pigment CSS 样板入手，观察其与 Emotion 方案在入口与类型声明上的差异。