如何在React.jsx中导入渲染MDX文件？解决导入报错问题

问题重现 #

你在React应用中尝试渲染MDX文件，Post.mdx内容：

//Post.mdx

---
title: Example Document
author: Jane Smith
date: August 15, 2023
---

# Welcome to My Example Document

This is a demonstration of an `.mdx` document with stylized content. Here, we'll explore some formatting options.

使用的JSX代码：

import { MDXProvider } from "@mdx-js/react";
import Post from './Post.mdx';

const components = {
  em: props => <i {...props} />
}

const Introduction = () => {
  return (
    <div className="container">
      <Sidebar />

      <div className="introduction">
        <Navbar />
        <div className="content">
          <MDXProvider components={components}>
            <Post />
          </MDXProvider>
        </div>
      </div>
    </div>
  );
};

export default Introduction;

触发错误：

Failed to execute 'createElement' on 'Document': The tag name provided ('/static/media/Post.c270f98726682967eabb.mdx') is not a valid name.

错误原因 #

这个错误的核心是：你的构建工具（如Webpack、Vite）没有正确识别MDX文件类型，将其当作普通静态资源处理，导致导入的Post是文件路径字符串，而非可渲染的React组件。

解决步骤 #

1. 安装MDX核心依赖 #

首先确保安装编译MDX所需的包：

npm install @mdx-js/loader @mdx-js/react
# 或用yarn
yarn add @mdx-js/loader @mdx-js/react

2. 配置构建工具处理MDX文件 #

根据你的React项目模板，选择对应配置方式：

场景1：Create React App（CRA）

CRA默认不支持MDX，需借助craco修改Webpack配置：

• 安装craco：

npm install @craco/craco --save-dev

• 项目根目录创建craco.config.js：

module.exports = {
  webpack: {
    configure: (webpackConfig) => {
      webpackConfig.module.rules.push({
        test: /\.mdx?$/,
        use: ['babel-loader', '@mdx-js/loader']
      });
      return webpackConfig;
    }
  }
};

• 修改package.json的启动脚本：

"scripts": {
  "start": "craco start",
  "build": "craco build",
  "test": "craco test"
}

场景2：Vite

Vite自带MDX支持，只需安装Rollup插件：

npm install @mdx-js/rollup --save-dev

• 修改vite.config.js：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import mdx from '@mdx-js/rollup';

export default defineConfig({
  plugins: [react(), mdx()]
});

场景3：自定义Webpack项目

直接在webpack.config.js的module.rules中添加规则：

module.exports = {
  // 其他配置...
  module: {
    rules: [
      // 其他规则...
      {
        test: /\.mdx?$/,
        use: ['babel-loader', '@mdx-js/loader']
      }
    ]
  }
};

3. 重启项目 #

配置完成后重启开发服务器，此时Post会被编译为React组件，可正常渲染。

额外：提取MDX头部元数据 #

如果需要读取MDX顶部的title、author等frontmatter信息，可使用gray-matter解析：

• 安装依赖：

npm install gray-matter

• 编写工具函数解析MDX：

import fs from 'fs';
import matter from 'gray-matter';
import { compile } from '@mdx-js/mdx';
import { jsx } from 'react/jsx-runtime';

export async function getMdxData(filePath) {
  const fileContent = fs.readFileSync(filePath, 'utf8');
  const { data: frontmatter, content } = matter(fileContent);
  const code = await compile(content, { outputFormat: 'function-body' });
  const Component = new Function('React', code)(jsx);
  return { frontmatter, Component };
}

• 在组件中使用：

import { useEffect, useState } from 'react';
import { MDXProvider } from '@mdx-js/react';

const components = { em: props => <i {...props} /> };

const Introduction = () => {
  const [postData, setPostData] = useState(null);

  useEffect(() => {
    const loadPost = async () => {
      const data = await getMdxData('./Post.mdx');
      setPostData(data);
    };
    loadPost();
  }, []);

  if (!postData) return <div>加载中...</div>;

  return (
    <div className="container">
      <Sidebar />
      <div className="introduction">
        <Navbar />
        <div className="content">
          <h1>{postData.frontmatter.title}</h1>
          <p>作者：{postData.frontmatter.author}</p>
          <MDXProvider components={components}>
            <postData.Component />
          </MDXProvider>
        </div>
      </div>
    </div>
  );
};

export default Introduction;

替代实现思路 #

1. Next.js官方MDX支持：使用@next/mdx插件，可直接将MDX作为路由页面或组件导入，支持SSR与SSG，配置简单。
2. mdx-bundler：适合动态编译MDX的场景，支持导入其他MDX、React组件，处理frontmatter更灵活。
3. Gatsby静态生成：借助gatsby-plugin-mdx在构建时预编译MDX为组件，提升运行时性能，适合静态站点。

内容的提问来源于stack exchange，提问作者Muhammed Didin