MDX-js/mdx 项目实战：按需编译与运行 MDX 内容

梅品万Rebecca

于 2025-06-02 09:02:13 发布

阅读量297

点赞数 3

本文链接：https://blog.youkuaiyun.com/gitblog_00197/article/details/148374987

版权

MDX-js/mdx 项目实战：按需编译与运行 MDX 内容

mdx Markdown for the component era 项目地址: https://gitcode.com/gh_mirrors/md/mdx

前言

在现代前端开发中，动态内容处理是一个常见需求。MDX-js/mdx 项目提供了一种强大的方式来处理 Markdown 和 JSX 混合内容。本文将深入探讨如何利用 MDX-js/mdx 实现按需编译和运行 MDX 内容的技术方案。

核心概念解析

什么是按需编译？

按需编译（On-Demand Compilation）是指在实际需要时才进行代码编译的过程，而不是在构建阶段就预先完成所有编译工作。这种方式特别适合内容频繁变化的场景，能够提供更好的开发体验和更灵活的部署方案。

MDX 编译流程

MDX-js/mdx 的编译流程主要分为两个阶段：

编译阶段：将 MDX 内容转换为可执行的 JavaScript 代码
运行阶段：在客户端执行编译后的代码，生成可渲染的 React 组件

基础实现方案

服务端编译

在服务端，我们使用 @mdx-js/mdx 的 compile 方法将 MDX 内容编译为 JavaScript 代码字符串：

import {compile} from '@mdx-js/mdx'

const code = String(await compile('# 你好', {
  outputFormat: 'function-body',
  // 其他编译选项...
}))

关键参数说明：

outputFormat: 'function-body'：指定输出格式为函数体，适合在客户端运行
其他选项可以控制 JSX 运行时、插件等配置

客户端运行

在客户端，我们使用 run 方法来执行编译后的代码：

import {run} from '@mdx-js/mdx'
import * as runtime from 'react/jsx-runtime'

const {default: Content} = await run(code, {
  ...runtime, 
  baseUrl: import.meta.url
})

运行结果中的 Content 就是一个可以直接渲染的 React 组件。

高级应用：Next.js 集成示例

在 Next.js 框架中，我们可以更优雅地实现这一流程：

import {compile, run} from '@mdx-js/mdx'
import {Fragment, useEffect, useState} from 'react'
import * as runtime from 'react/jsx-runtime'

export default function Page({code}) {
  const [mdxModule, setMdxModule] = useState()
  const Content = mdxModule ? mdxModule.default : Fragment

  useEffect(() => {
    (async () => {
      setMdxModule(await run(code, {...runtime, baseUrl: import.meta.url}))
    })()
  }, [code])

  return <Content />
}

export async function getStaticProps() {
  const code = String(
    await compile('# 你好', {
      outputFormat: 'function-body'
      // 其他编译选项...
    })
  )
  return {props: {code}}
}

这个实现方案有几个关键点：