MDX 与课时渲染

这一课你将能做到

1. 说清 Markdown 与 MDX 的关系：MDX = Markdown + 可嵌入的 React 组件
2. 在 Next.js 里配置 @next/mdx，写出带自定义组件的 .mdx 页面
3. 理解本站课时内容「服务端读源 → 渲染 → 消毒 → 输出」的完整管线

为什么要学

做内容型产品（文档站、课程平台、博客）绕不开一个问题：内容用什么格式写、怎么安全地渲染成页面？Markdown 是事实标准——写作友好、程序员都会；但它有个天花板：只能表达文字排版，表达不了交互。想在一篇文章里嵌一个可运行的代码沙盒、一个折叠面板、一道点击出答案的练习题，纯 Markdown 做不到。

MDX 补上这块：在 Markdown 里直接写 JSX，内容作者可以像用 HTML 标签一样用你封装好的 React 组件。本学习平台的课时内容就是按这条思路处理的——你此刻正在读的这篇课文的排版结构，最终都由 React 组件渲染出来；平台还支持课时里嵌练习与测验组件，这正是 MDX 的能力域。

面试场景虽不如 RSC 高频，但「Markdown 渲染的安全问题（XSS）」是个好的加分话题——任何用户可控内容进 HTML 都要消毒（sanitize），本站专门有 mdxSanitize 模块处理这件事，说明这不是纸上谈兵。

先建立图像

Markdown 与 MDX 的对比：

普通 Markdown（.md）                MDX（.mdx）
# 标题                              # 标题
- 列表                              - 列表
**加粗**                            **加粗**

❌ 不能写组件                        ✅ 可以写组件：
                                    <Callout type="warn">注意！</Callout>
                                    <Quiz question="1+1=?" answer="2" />

在 Next.js 生态里的位置：

写作源文件           Next.js 渲染管线              用户看到
.mdx 文件    ──→   @next/mdx 编译        ──→    页面（编译期，构建时确定）
─────────────
数据库/API 里的 markdown 字符串 ──→ 动态渲染库 + sanitize ──→ 页面（运行时）
（如本站后端下发的 contentMd）

两种来源决定两种技术路线，本课两条都讲：

内容来源	技术路线	特点
仓库里的 .mdx 文件	@next/mdx 官方方案	编译进构建，类型安全，改内容要重新部署
后端/API 下发的字符串	运行时渲染（如 next-mdx-remote 或自研管线）	内容可后台随时更新，必须做安全消毒

本站属于第二种：Spring Boot 后端把课时 contentMd 下发给前端，Next.js 服务端渲染成 React 元素。

跟着做

步骤 1：安装并配置 @next/mdx

npm install @next/mdx @mdx-js/loader @mdx-js/react @types/mdx

修改 next.config.ts（或新建 next.config.mjs）：

import type { NextConfig } from "next";
import createMDX from "@next/mdx";

const nextConfig: NextConfig = {
  pageExtensions: ["ts", "tsx", "md", "mdx"], // 让 Next 把 .mdx 也当页面
};

const withMDX = createMDX({
  // 可加 remark/rehype 插件，如 remarkGfm（表格、删除线）
  // options: { remarkPlugins: [remarkGfm] },
});

export default withMDX(nextConfig);