在 Next.js 中使用 Markdown 与 MDX

0290

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

例如，写下以下 Markdown：

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

会得到下面的 HTML：

<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 的页面。

根据使用的包管理器，选择相应命令安装依赖。

pnpm：

pnpm add @next/mdx @mdx-js/loader @mdx-js/react @types/mdx

npm：

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

yarn：

yarn add @next/mdx @mdx-js/loader @mdx-js/react @types/mdx

bun：

bun add @next/mdx @mdx-js/loader @mdx-js/react @types/mdx

配置 next.config.mjs

更新项目根目录下的 next.config.mjs，启用 MDX：

import createMDX from '@next/mdx'

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Configure `pageExtensions` to include markdown and MDX files
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
  // Optionally, add any other Next.js config below
}

const withMDX = createMDX({
  // Add markdown plugins here, as desired
})

// Merge MDX config with Next.js config
export default withMDX(nextConfig)

配置完成后，.mdx 文件便可以作为应用中的页面、路由或被导入的模块。

处理 .md 文件

默认情况下，@next/mdx 只编译 .mdx 扩展名的文件。如果要通过 webpack 处理 .md 文件，修改 extension 选项：

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

添加 mdx-components.tsx

在项目根目录创建 mdx-components.tsx 或 mdx-components.js，定义全局 MDX 组件。它可以与 pages 或 app 同级；如果项目采用 src 目录，也可以放在其中。

TypeScript 版本：

import type { MDXComponents } from 'mdx/types'

const components: MDXComponents = {}

export function useMDXComponents(): MDXComponents {
  return components
}

JavaScript 版本：

const components = {}

export function useMDXComponents() {
  return components
}

注意：

  • 在 App Router 中使用 @next/mdx，必须提供 mdx-components.tsx 或对应的 JavaScript 文件，否则无法工作。
  • 更多约定见 mdx-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'

# Welcome to my MDX page!

This is some **bold** and _italics_ text.

This is a list in markdown:

- One
- Two
- Three

Checkout my React component:

<MyComponent />

访问 /mdx-page 路由，即可显示渲染后的 MDX 页面。

使用导入

在 /app 中创建页面，并把 MDX 文件放在所需位置：

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

例如，markdown/welcome.mdx 可以包含 Markdown 和导入的 React 组件：

import { MyComponent } from 'my-component'

# Welcome to my MDX page!

This is some **bold** and _italics_ text.

This is a list in markdown:

- One
- Two
- Three

Checkout my React component:

<MyComponent />

在页面中导入该 MDX 文件，便可显示内容。TypeScript 页面示例：

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

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

JavaScript 页面示例：

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

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

同样，访问 /mdx-page 将显示渲染后的页面。

使用动态导入

也可以动态导入 MDX 组件，而不把每个 MDX 文件直接作为文件路由。例如，通过动态路由段从独立目录加载 MDX 组件：

动态 MDX 组件的路由目录结构

generateStaticParams 可以预渲染给定路由。将 dynamicParams 设置为 false 后，访问未在 generateStaticParams 中列出的路由会返回 404。

TypeScript 示例，文件为 app/blog/[slug]/page.tsx：

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

JavaScript 示例，文件为 app/blog/[slug]/page.js：

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 元素。例如：

## This is a heading

This is a list in markdown:

- One
- Two
- Three

会生成：

<h2>This is a heading</h2>

<p>This is a list in markdown:</p>

<ul>
  <li>One</li>
  <li>Two</li>
  <li>Three</li>
</ul>

可以提供自定义组件，将它们映射到生成的 HTML 元素，从而为 Markdown 设置样式。样式和组件可以全局配置、局部配置，也可以通过共享布局实现。

全局样式与组件

在 mdx-components.tsx 中添加样式和组件，会影响应用内所有 MDX 文件。

TypeScript 示例：

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

// This file allows you to provide custom React components
// to be used in MDX files. You can import and use any
// React component you want, including inline styles,
// components from other libraries, and more.

const components = {
  // Allows customizing built-in components, e.g. to add styling.
  h1: ({ children }) => (
    <h1 style={{ color: 'red', fontSize: '48px' }}>{children}</h1>
  ),
  img: (props) => (
    <Image
      sizes="100vw"
      style={{ width: '100%', height: 'auto' }}
      {...(props as ImageProps)}
    />
  ),
} satisfies MDXComponents

export function useMDXComponents(): MDXComponents {
  return components
}

JavaScript 示例：

import Image from 'next/image'

// This file allows you to provide custom React components
// to be used in MDX files. You can import and use any
// React component you want, including inline styles,
// components from other libraries, and more.

const components = {
  // Allows customizing built-in components, e.g. to add styling.
  h1: ({ children }) => (
    <h1 style={{ color: 'red', fontSize: '48px' }}>{children}</h1>
  ),
  img: (props) => (
    <Image sizes="100vw" style={{ width: '100%', height: 'auto' }} {...props} />
  ),
}

export function useMDXComponents() {
  return components
}

局部样式与组件

可以向导入的 MDX 组件传递组件映射，为某个页面应用局部样式。这些配置会与全局配置合并，并覆盖同名全局组件。

TypeScript 示例：

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} />
}

JavaScript 示例：

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 内置的布局支持。

app/mdx-page/layout.tsx 示例：

export default function MdxLayout({ children }: { children: React.ReactNode }) {
  // Create any shared layout or styles here
  return <div style={{ color: 'blue' }}>{children}</div>
}

对应的 JavaScript 版本：

export default function MdxLayout({ children }) {
  // Create any shared layout or styles here
  return <div style={{ color: 'blue' }}>{children}</div>
}

使用 Tailwind Typography 插件

如果应用使用 Tailwind 设置样式，可以通过 @tailwindcss/typography 插件，在 Markdown 文件中复用 Tailwind 配置与样式。

该插件提供一组 prose 类，用于为 Markdown 等来源的内容块添加排版样式。安装 Tailwind Typography 后，可结合共享布局应用所需的 prose 类。

TypeScript 示例：

export default function MdxLayout({ children }: { children: React.ReactNode }) {
  // Create any shared layout or styles here
  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>
  )
}

JavaScript 示例：

export default function MdxLayout({ children }) {
  // Create any shared layout or styles here
  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 默认不支持 frontmatter，但可以借助以下方案将其加入 MDX 内容：

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

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

# Blog post

随后，可以在 MDX 文件外引用这些元数据。TypeScript 示例：

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

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

JavaScript 示例：

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

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

一个常见用途是遍历一组 MDX 文件并提取数据，例如根据所有博客文章生成博客索引页。可以使用 Node.js 的 fs 模块或 globby 读取文章目录并提取元数据。

注意，fs、globby 等只能在服务器端使用。完整示例可参考 Portfolio Starter Kit。

remark 与 rehype 插件

可以按需提供 remark 和 rehype 插件来转换 MDX 内容。例如，使用 remark-gfm 支持 GitHub Flavored Markdown。

由于 remark 和 rehype 生态仅支持 ESM，需要将配置文件命名为 next.config.mjs 或 next.config.ts：

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

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Allow .mdx extensions for files
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
  // Optionally, add any other Next.js config below
}

const withMDX = createMDX({
  // Add markdown plugins here, as desired
  options: {
    remarkPlugins: [remarkGfm],
    rehypePlugins: [],
  },
})

// Combine MDX and Next.js config
export default withMDX(nextConfig)

在 Turbopack 中使用插件

要在 Turbopack 中使用这些插件，应升级至最新的 @next/mdx，并用字符串指定插件名称：

import createMDX from '@next/mdx'

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

const withMDX = createMDX({
  options: {
    remarkPlugins: [
      // Without options
      'remark-gfm',
      // With options
      ['remark-toc', { heading: 'The Table' }],
    ],
    rehypePlugins: [
      // Without options
      'rehype-slug',
      // With options
      ['rehype-katex', { strict: true, throwOnError: true }],
    ],
  },
})

export default withMDX(nextConfig)

提示：选项无法序列化的 remark 或 rehype 插件，目前不能与 Turbopack 配合使用，因为 JavaScript 函数无法传递给 Rust。

深入理解：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) // Convert into markdown AST
    .use(remarkRehype) // Transform to HTML AST
    .use(rehypeSanitize) // Sanitize HTML input
    .use(rehypeStringify) // Convert AST into serialized HTML
    .process('Hello, Next.js!')

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

这两个生态还提供语法高亮、标题链接、目录生成等插件。

按照前文使用 @next/mdx 时，不需要直接调用 remark 或 rehype，因为这些工作已经由包完成。本节只是解释 @next/mdx 底层的处理方式。

使用基于 Rust 的 MDX 编译器（实验性）

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

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

mdxRs 也接受对象，用来配置 MDX 文件的转换方式：

module.exports = withMDX({
  experimental: {
    mdxRs: {
      jsxRuntime?: string            // Custom jsx runtime
      jsxImportSource?: string       // Custom jsx import source,
      providerImportSource?: string  // Module providing a `useMDXComponents` context
      mdxType?: 'gfm' | 'commonmark' // Configure what kind of mdx syntax will be used to parse & transform
    },
  },
})

相关链接

原文来源：How to use markdown and MDX in Next.js。本文依据留存原文译为中文，代码示例按原文保留。

© 2026 Vercel, Inc.

© 版权声明
文章版权归作者所有，未经允许请勿转载。
THE END
技术译文
喜欢就支持一下吧
点赞0 分享
彩雨伞的头像-未完纪钻石会员
Self-introduction-未完纪
Self-introduction
Self-introduction
6天前 71
使用宝塔为 AList 配置反向代理与 HTTPS-未完纪
使用宝塔为 AList 配置反向代理与 HTTPS
使用宝塔为 AList 配置反向代理与 HTTPS
昨天 59
WordPress 接入 Microsoft Clarity Cookie 同意与偏好设置-未完纪
WordPress 接入 Microsoft Clarity Cookie 同意与偏好设置
WordPress 接入 Microsoft Clarity Cookie 同意与偏好设置
昨天 56
注册区块变体，同时在插入器中隐藏它-未完纪
注册区块变体，同时在插入器中隐藏它
注册区块变体，同时在插入器中隐藏它
21小时前 56
Windows快速部署OpenClaw + Qwen3.5 Plus完整教程-未完纪
Windows快速部署OpenClaw + Qwen3.5 Plus完整教程
Windows快速部署OpenClaw + Qwen3.5 Plus完整教程
前天 55
从用户序列到扩展规律：Meta 广告排序的多阶段架构-未完纪
从用户序列到扩展规律：Meta 广告排序的多阶段架构
从用户序列到扩展规律：Meta 广告排序的多阶段架构
12小时前 54
相关推荐
注册区块变体，同时在插入器中隐藏它-未完纪
注册区块变体，同时在插入器中隐藏它
注册区块变体，同时在插入器中隐藏它
21小时前 56
用 Ansible 定制 Loki 部署-未完纪
用 Ansible 定制 Loki 部署
用 Ansible 定制 Loki 部署
17小时前 54
用内部审计器测试数百个网页的 Cookie 行为-未完纪
用内部审计器测试数百个网页的 Cookie 行为
用内部审计器测试数百个网页的 Cookie 行为
20小时前 54
从用户序列到扩展规律：Meta 广告排序的多阶段架构-未完纪
从用户序列到扩展规律：Meta 广告排序的多阶段架构
从用户序列到扩展规律：Meta 广告排序的多阶段架构
12小时前 54
Loki 简明指南：处理乱序日志与旧日志-未完纪
Loki 简明指南：处理乱序日志与旧日志
Loki 简明指南：处理乱序日志与旧日志
昨天 53
用维度表加速字符串聚合-未完纪
用维度表加速字符串聚合
用维度表加速字符串聚合
昨天 53
评论 抢沙发

请登录后发表评论

    暂无评论内容