logoNext.js 简体中文
文档博客学习
简介/指南/MDX

在 Next.js 中使用 Markdown 和 MDX

Markdown 是一种轻量级标记语言，用于格式化文本。它允许您使用纯文本语法编写内容，并将其转换为结构有效的 HTML。它通常用于网站和博客的内容编写。

您可以这样写...

I **love** using [Next.js](https://nextjs.org/)

输出：

<p>I <strong>love</strong> using <a href="https://nextjs.org/">Next.js</a></p>

MDX 是 Markdown 的超集，允许您直接在 Markdown 文件中编写 JSX。这是一种强大的方式，可以在内容中添加动态交互性和嵌入 React 组件。

Next.js 既支持应用程序内的本地 MDX 内容，也支持在服务器上动态获取的远程 MDX 文件。Next.js 插件处理将 Markdown 和 React 组件转换为 HTML，包括在服务端组件（App Router 中的默认组件）中的使用支持。

须知：查看 Portfolio Starter Kit 模板获取完整的工作示例。

安装依赖

@next/mdx 包及相关包用于配置 Next.js 以处理 Markdown 和 MDX。它从本地文件获取数据，允许您直接在 /pages 或 /app 目录中创建 .md 或 .mdx 扩展名的页面。

安装以下包以在 Next.js 中渲染 MDX：

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

配置 next.config.mjs

更新项目根目录下的 next.config.mjs 文件以配置使用 MDX：

next.config.mjs
import createMDX from '@next/mdx'

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 配置 `pageExtensions` 以包含 Markdown 和 MDX 文件
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
  // 可选，添加其他 Next.js 配置
}

const withMDX = createMDX({
  // 根据需要在此添加 Markdown 插件
})

// 将 MDX 配置与 Next.js 配置合并
export default withMDX(nextConfig)

这允许 .mdx 文件在您的应用程序中作为页面、路由或导入使用。

处理 .md 文件

默认情况下，next/mdx 仅编译 .mdx 扩展名的文件。要使用 webpack 处理 .md 文件，请更新 extension 选项：

next.config.mjs
const withMDX = createMDX({
  extension: /\.(md|mdx)$/,
})

须知：Turbopack 目前不支持 extension 选项，因此不支持 .md 文件。

添加 mdx-components.tsx 文件

在项目根目录下创建 mdx-components.tsx（或 .js）文件以定义全局 MDX 组件。例如，与 pages 或 app 同级，或在适用的情况下位于 src 内。

import type { MDXComponents } from 'mdx/types'

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    ...components,
  }
}
export function useMDXComponents(components) {
  return {
    ...components,
  }
}

须知：

渲染 MDX

您可以使用 Next.js 的文件路由或通过将 MDX 文件导入其他页面来渲染 MDX。

使用文件路由

使用文件路由时，您可以像使用任何其他页面一样使用 MDX 页面。

在 App Router 应用中，这包括能够使用 元数据。

在 /app 目录中创建一个新的 MDX 页面：

  my-project
  ├── app
  │   └── mdx-page
  │       └── page.(mdx/md)
  |── mdx-components.(tsx/js)
  └── package.json

您可以在这些文件中使用 MDX，甚至可以直接在 MDX 页面中导入 React 组件：

import { MyComponent } from 'my-component'

# 欢迎来到我的 MDX 页面！

这是一些 **粗体** 和 _斜体_ 文本。

这是一个 Markdown 列表：

- 一
- 二
- 三

看看我的 React 组件：

<MyComponent />

导航到 /mdx-page 路由应显示您渲染的 MDX 页面。

使用导入

在 /app 目录中创建一个新页面，并在您想要的任何位置创建一个 MDX 文件：

  .
  ├── app/
  │   └── mdx-page/
  │       └── page.(tsx/js)
  ├── markdown/
  │   └── welcome.(mdx/md)
  ├── mdx-components.(tsx/js)
  └── package.json

您可以在这些文件中使用 MDX，甚至可以直接在 MDX 页面中导入 React 组件：

import { MyComponent } from 'my-component'

# 欢迎来到我的 MDX 页面！

这是一些 **粗体** 和 _斜体_ 文本。

这是一个 Markdown 列表：

- 一
- 二
- 三

看看我的 React 组件：

<MyComponent />

在页面中导入 MDX 文件以显示内容：

import Welcome from '@/markdown/welcome.mdx'

export default function Page() {
  return <Welcome />
}
import Welcome from '@/markdown/welcome.mdx'

export default function Page() {
  return <Welcome />
}

导航到 /mdx-page 路由应显示您渲染的 MDX 页面。

使用动态导入

您可以使用动态导入的 MDX 组件，而不是使用文件系统路由来处理 MDX 文件。

例如，您可以有一个动态路由段，从单独的目录加载 MDX 组件：

动态 MDX 组件的路由段

generateStaticParams 可用于预渲染提供的路由。通过将 dynamicParams 标记为 false，访问未在 generateStaticParams 中定义的路由将返回 404。

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const { default: Post } = await import(`@/content/${slug}.mdx`)

  return <Post />
}

export function generateStaticParams() {
  return [{ slug: 'welcome' }, { slug: 'about' }]
}

export const dynamicParams = false
export default async function Page({ params }) {
  const { slug } = await params
  const { default: Post } = await import(`@/content/${slug}.mdx`)

  return <Post />
}

export function generateStaticParams() {
  return [{ slug: 'welcome' }, { slug: 'about' }]
}

export const dynamicParams = false

须知：确保在导入中指定 .mdx 文件扩展名。虽然不需要使用 模块路径别名（例如 @/content），但它确实简化了您的导入路径。

使用自定义样式和组件

Markdown 在渲染时会映射到原生 HTML 元素。例如，编写以下 Markdown：

## 这是一个标题

这是一个 Markdown 列表：

- 一
- 二
- 三

生成以下 HTML：

<h2>这是一个标题</h2>

<p>这是一个 Markdown 列表：</p>

<ul>
  <li>一</li>
  <li>二</li>
  <li>三</li>
</ul>

要为您的 Markdown 添加样式，您可以提供映射到生成的 HTML 元素的自定义组件。样式和组件可以在全局、局部以及共享布局中实现。

全局样式和组件

在 mdx-components.tsx 中添加样式和组件将影响应用程序中的 所有 MDX 文件。

import type { MDXComponents } from 'mdx/types'
import Image, { ImageProps } from 'next/image'

// 此文件允许您提供自定义 React 组件
// 用于 MDX 文件。您可以导入和使用任何
// React 组件，包括内联样式、
// 来自其他库的组件等。

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    // 允许自定义内置组件，例如添加样式。
    h1: ({ children }) => (
      <h1 style={{ color: 'red', fontSize: '48px' }}>{children}</h1>
    ),
    img: (props) => (
      <Image
        sizes="100vw"
        style={{ width: '100%', height: 'auto' }}
        {...(props as ImageProps)}
      />
    ),
    ...components,
  }
}
import Image from 'next/image'

// 此文件允许您提供自定义 React 组件
// 用于 MDX 文件。您可以导入和使用任何
// React 组件，包括内联样式、
// 来自其他库的组件等。

export function useMDXComponents(components) {
  return {
    // 允许自定义内置组件，例如添加样式。
    h1: ({ children }) => (
      <h1 style={{ color: 'red', fontSize: '48px' }}>{children}</h1>
    ),
    img: (props) => (
      <Image
        sizes="100vw"
        style={{ width: '100%', height: 'auto' }}
        {...props}
      />
    ),
    ...components,
  }
}

局部样式和组件

您可以通过将样式和组件传递给导入的 MDX 组件来将它们应用于特定页面。这些将与 全局样式和组件 合并并覆盖它们。

import Welcome from '@/markdown/welcome.mdx'

function CustomH1({ children }) {
  return <h1 style={{ color: 'blue', fontSize: '100px' }}>{children}</h1>
}

const overrideComponents = {
  h1: CustomH1,
}

export default function Page() {
  return <Welcome components={overrideComponents} />
}
import Welcome from '@/markdown/welcome.mdx'

function CustomH1({ children }) {
  return <h1 style={{ color: 'blue', fontSize: '100px' }}>{children}</h1>
}

const overrideComponents = {
  h1: CustomH1,
}

export default function Page() {
  return <Welcome components={overrideComponents} />
}

共享布局

要在 MDX 页面之间共享布局，您可以使用 App Router 的 内置布局支持。

export default function MdxLayout({ children }: { children: React.ReactNode }) {
  // 在此创建任何共享布局或样式
  return <div style={{ color: 'blue' }}>{children}</div>
}
export default function MdxLayout({ children }) {
  // 在此创建任何共享布局或样式
  return <div style={{ color: 'blue' }}>{children}</div>
}

使用 Tailwind 排版插件

如果您使用 Tailwind 来设计应用程序样式，配合 @tailwindcss/typography 插件 可以复用您的 Tailwind 配置和样式到 Markdown 文件中。

该插件提供了一组 prose 类，可用于为来自 Markdown 等内容源的区块添加排版样式。

安装 Tailwind 排版插件 并与 共享布局 结合使用，添加所需的 prose 样式。

export default function MdxLayout({ children }: { children: React.ReactNode }) {
  // 在此创建共享布局或样式
  return (
    <div className="prose prose-headings:mt-8 prose-headings:font-semibold prose-headings:text-black prose-h1:text-5xl prose-h2:text-4xl prose-h3:text-3xl prose-h4:text-2xl prose-h5:text-xl prose-h6:text-lg dark:prose-headings:text-white">
      {children}
    </div>
  )
}
export default function MdxLayout({ children }) {
  // 在此创建共享布局或样式
  return (
    <div className="prose prose-headings:mt-8 prose-headings:font-semibold prose-headings:text-black prose-h1:text-5xl prose-h2:text-4xl prose-h3:text-3xl prose-h4:text-2xl prose-h5:text-xl prose-h6:text-lg dark:prose-headings:text-white">
      {children}
    </div>
  )
}

前言 (Frontmatter)

前言 (Frontmatter) 是一种类似 YAML 的键值对结构，可用于存储页面相关数据。@next/mdx 默认 不 支持前言，但可以通过以下方案添加：

@next/mdx 允许 像普通 JavaScript 组件一样使用导出：

export const metadata = {
  author: 'John Doe',
}

# 博客文章

现在可以在 MDX 文件外部引用元数据：

import BlogPost, { metadata } from '@/content/blog-post.mdx'

export default function Page() {
  console.log('metadata: ', metadata)
  //=> { author: 'John Doe' }
  return <BlogPost />
}
import BlogPost, { metadata } from '@/content/blog-post.mdx'

export default function Page() {
  console.log('metadata: ', metadata)
  //=> { author: 'John Doe' }
  return <BlogPost />
}

常见用例是当您需要遍历 MDX 集合并提取数据时，例如从所有博客文章创建索引页。可以使用 Node 的 fs 模块 或 globby 等工具读取文章目录并提取元数据。

须知：

  • fs、globby 等工具仅能在服务端使用。
  • 查看 Portfolio Starter Kit 模板获取完整示例。

remark 和 rehype 插件

您可以选择性地提供 remark 和 rehype 插件来转换 MDX 内容。

例如，使用 remark-gfm 来支持 GitHub 风格的 Markdown。

由于 remark 和 rehype 生态系统仅支持 ESM，您需要使用 next.config.mjs 或 next.config.ts 作为配置文件。

next.config.mjs
import remarkGfm from 'remark-gfm'
import createMDX from '@next/mdx'

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 允许 .mdx 文件扩展名
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
  // 可选，添加其他 Next.js 配置
}

const withMDX = createMDX({
  // 在此添加所需的 Markdown 插件
  options: {
    remarkPlugins: [remarkGfm],
    rehypePlugins: [],
  },
})

// 合并 MDX 和 Next.js 配置
export default withMDX(nextConfig)

在 Turbopack 中使用插件

要在 Turbopack 中使用插件，请升级到最新版 @next/mdx 并使用字符串指定插件名称：

next.config.mjs
import createMDX from '@next/mdx'

/** @type {import('next').NextConfig} */
const nextConfig = {
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
}

const withMDX = createMDX({
  options: {
    remarkPlugins: [],
    rehypePlugins: [['rehype-katex', { strict: true, throwOnError: true }]],
  },
})

export default withMDX(nextConfig)

须知：

由于 无法将 JavaScript 函数传递到 Rust，带有不可序列化选项的 remark 和 rehype 插件目前无法与 Turbopack 一起使用。

远程 MDX

如果您的 MDX 文件或内容存储在 其他地方，可以在服务端动态获取。这对于存储在 CMS、数据库或其他地方的内容非常有用。社区包 next-mdx-remote-client 适用于此场景。

须知：请谨慎操作。MDX 会编译为 JavaScript 并在服务端执行。您应该仅从可信来源获取 MDX 内容，否则可能导致远程代码执行 (RCE)。

以下示例使用 next-mdx-remote-client：

import { MDXRemote } from 'next-mdx-remote-client/rsc'

export default async function RemoteMdxPage() {
  // MDX 文本 - 可来自数据库、CMS、fetch 请求等...
  const res = await fetch('https://...')
  const markdown = await res.text()
  return <MDXRemote source={markdown} />
}
import { MDXRemote } from 'next-mdx-remote-client/rsc'

export default async function RemoteMdxPage() {
  // MDX 文本 - 可来自数据库、CMS、fetch 请求等...
  const res = await fetch('https://...')
  const markdown = await res.text()
  return <MDXRemote source={markdown} />
}

访问 /mdx-page-remote 路由将显示渲染后的 MDX 内容。

深入解析：如何将 Markdown 转换为 HTML？

React 本身不理解 Markdown。Markdown 纯文本需要先转换为 HTML。这可以通过 remark 和 rehype 实现。

remark 是围绕 Markdown 的工具生态系统，rehype 则是针对 HTML 的生态系统。例如，以下代码片段将 Markdown 转换为 HTML：

import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import rehypeSanitize from 'rehype-sanitize'
import rehypeStringify from 'rehype-stringify'

main()

async function main() {
  const file = await unified()
    .use(remarkParse) // 转换为 Markdown AST
    .use(remarkRehype) // 转换为 HTML AST
    .use(rehypeSanitize) // 清理 HTML 输入
    .use(rehypeStringify) // 将 AST 转换为序列化 HTML
    .process('Hello, Next.js!')

  console.log(String(file)) // <p>Hello, Next.js!</p>
}

remark 和 rehype 生态系统包含 语法高亮、标题链接、生成目录 等插件。

当使用上述 @next/mdx 时，您 无需 直接使用 remark 或 rehype，因为它们已自动处理。此处描述是为了深入理解 @next/mdx 的内部机制。

使用基于 Rust 的 MDX 编译器 (实验性)

Next.js 支持一个用 Rust 编写的新 MDX 编译器。该编译器仍处于实验阶段，不建议在生产环境中使用。要使用新编译器，需要在 next.config.js 中配置 withMDX：

next.config.js
module.exports = withMDX({
  experimental: {
    mdxRs: true,
  },
})

mdxRs 也接受一个对象来配置如何转换 MDX 文件。

next.config.js
module.exports = withMDX({
  experimental: {
    mdxRs: {
      jsxRuntime?: string            // 自定义 JSX 运行时
      jsxImportSource?: string       // 自定义 JSX 导入源
      mdxType?: 'gfm' | 'commonmark' // 配置用于解析和转换的 MDX 语法类型
    },
  },
})

实用链接

开发环境

了解如何使用 Next.js 优化您的本地开发环境。

内存使用

优化开发和生产环境中应用程序的内存占用。