MDX 核心三件套：编译器、加载器与运行时的架构分工

在构建基于内容的 React 应用时，开发者常面对 @mdx-js/mdx、@mdx-js/loader 和 @mdx-js/react 这三个包感到困惑。它们名字相似，却处于构建流水线的不同阶段。选错包会导致构建失败、运行时错误或架构耦合度过高。本文将从工程实践角度，拆解它们的真实职责与协作方式。

🏭 核心职责：编译 vs 集成 vs 渲染

这三个包分别对应内容处理流水线的三个独立环节：编译源代码、集成到构建系统、在浏览器中渲染。

@mdx-js/mdx 是纯编译器。
它只关心一件事：把 MDX 文本变成 JavaScript 代码字符串。它不知道 webpack 是什么，也不关心 React 是否存在。你可以把它看作一个黑盒函数：输入字符串，输出字符串。

// 使用 @mdx-js/mdx 进行纯编译
import { compile } from '@mdx-js/mdx';

const mdxText = '# Hello\n\n<Counter />';

async function compileExample() {
  const result = await compile(mdxText, {
    outputFormat: 'function-body',
    development: false
  });
  
  console.log(String(result)); 
  // 输出：const {useMDXComponents: _provideComponents} = arguments[0];
  // return <h1>{`Hello`}</h1>\n<_provideComponents().Counter />;
}

@mdx-js/loader 是 webpack 适配器。
它的作用是在 webpack 构建过程中拦截 .mdx 文件，调用编译器，并将结果转换为 webpack 能理解的模块。它让 import Page from './page.mdx' 成为可能。

// webpack.config.js 配置 @mdx-js/loader
module.exports = {
  module: {
    rules: [
      {
        test: /.mdx?$/,
        use: [
          {
            loader: '@mdx-js/loader',
            options: {
              providerImportSource: '@mdx-js/react',
              development: process.env.NODE_ENV === 'development'
            }
          }
        ]
      }
    ]
  }
};

// 业务代码中直接导入
import BlogPost from './blog-post.mdx';
// webpack 会自动调用 loader 处理该文件

@mdx-js/react 是运行时环境。
编译后的代码需要特定的 React 上下文才能工作。这个包提供了 MDXProvider 组件，用于注入自定义组件映射表，并处理组件查找逻辑。没有它，编译出的代码会因找不到 _provideComponents 而报错。

// 在 React 应用入口包裹 MDXProvider
import { MDXProvider } from '@mdx-js/react';
import { h1, a, pre } from './custom-components';

const components = { h1, a, pre };

function App({ children }) {
  return (
    <MDXProvider components={components}>
      {children}
    </MDXProvider>
  );
}

// 编译后的 MDX 组件内部会调用 useMDXComponents() 
// 从 MDXProvider 的上下文中获取自定义组件

🔌 集成模式：手动调用 vs 自动拦截

选择哪个包，本质上取决于你希望如何控制编译过程。

手动控制流程（使用 @mdx-js/mdx）
适用于非标准构建环境。例如，你可能需要在服务端按需编译用户提交的内容，或者在 Vite 中编写自定义插件。

// 场景：在 Node.js 服务端动态编译
import { compile } from '@mdx-js/mdx';
import { renderToString } from 'react-dom/server';
import { createRoot } from 'react-dom/client'; // 假设有运行时环境

async function renderUserContent(content) {
  const { default: MDXContent } = await compile(content, {
    outputFormat: 'function-body'
  });
  
  // 注意：这里需要手动处理 React 环境注入
  // 实际生产中需配合 @mdx-js/react 的上下文机制
  return renderToString(<MDXContent />);
}

自动构建集成（使用 @mdx-js/loader）
适用于标准 webpack 项目。你无需在业务代码中调用编译函数，只需配置规则，构建工具会自动处理。

// 场景：Next.js 或 Create React App 项目
// 只需在 next.config.js 或 webpack 配置中添加 loader
// 业务代码保持简洁

import Article from './articles/intro.mdx';

function Page() {
  return (
    <main>
      <Article /> {/* 直接作为组件使用 */}
    </main>
  );
}

⚙️ 配置差异：编译选项 vs 加载器选项

虽然 @mdx-js/loader 内部调用了 @mdx-js/mdx，但它们的配置层级不同。加载器的选项会透传给编译器，但增加了构建特定的配置项。

@mdx-js/mdx 关注语言特性。
配置项主要涉及语法解析、输出格式和插件链。

// @mdx-js/mdx 配置示例
await compile(text, {
  recmaPlugins: [myRecmaPlugin], // 操作 ESTree
  rehypePlugins: [myRehypePlugin], // 操作 HTML AST
  remarkPlugins: [myRemarkPlugin], // 操作 Markdown AST
  outputFormat: 'function-body', // 输出函数体还是完整模块
  development: true // 包含调试信息
});

@mdx-js/loader 关注构建集成。
除了透传上述选项外，还必须指定 React 组件的来源，以便编译后的代码知道从哪里导入 MDXProvider 相关逻辑。

// @mdx-js/loader 配置示例
{
  loader: '@mdx-js/loader',
  options: {
    providerImportSource: '@mdx-js/react', // 必填：指定运行时包
    remarkPlugins: [/* 透传给编译器 */],
    format: 'detect', // 自动检测 .md 还是 .mdx
    webpackLoaderOptions: { /* webpack 特定选项 */ }
  }
}

🛑 常见误区与避坑指南

误区一：以为安装了 loader 就不需要 react 包
很多开发者只安装了 @mdx-js/loader，却在运行时遇到 _provideComponents is not defined 错误。这是因为 loader 只负责编译，生成的代码仍然依赖 @mdx-js/react 提供的运行时环境。必须同时安装并配置 MDXProvider。

误区二：在非 webpack 项目中强行使用 loader
@mdx-js/loader 仅对 webpack 有效。如果在 Vite、Rollup 或 Esbuild 项目中尝试使用它，构建会直接失败。这些工具需要各自的插件（如 @mdx-js/rollup 或 @mdx-js/esbuild），但底层编译器依然是 @mdx-js/mdx。

误区三：混淆编译时与运行时错误
如果 MDX 语法有误，@mdx-js/mdx 或 @mdx-js/loader 会在构建阶段报错。但如果 MDXProvider 未正确包裹，错误会在浏览器运行时出现。调试时需区分错误发生的时间点。

// 错误示范：缺少 MDXProvider 包裹
function App() {
  return <BlogPost />; // 运行时可能报错，找不到组件上下文
}

// 正确示范
function App() {
  return (
    <MDXProvider components={{ h1: CustomH1 }}>
      <BlogPost />
    </MDXProvider>
  );
}

📊 决策矩阵：根据场景选型

💡 架构建议

在现代前端架构中，建议遵循"关注点分离"原则：

1. 编译层：始终依赖 @mdx-js/mdx 作为核心引擎。即使使用 loader，也要明白它只是包装器。
2. 构建层：根据构建工具选择适配器。webpack 用 @mdx-js/loader，其他工具寻找社区插件或直接调用编译器 API。
3. 渲染层：永远不要省略 @mdx-js/react。它是连接编译产物与 React 树的桥梁。

这种分层设计让你的系统更具弹性。如果未来从 webpack 迁移到 Vite，只需替换构建层适配器，核心编译逻辑和渲染组件无需改动。

🎯 总结

@mdx-js/mdx 是引擎，@mdx-js/loader 是变速箱，@mdx-js/react 是车轮。引擎产生动力，变速箱将动力传递给车轮，车轮让车跑起来。缺一不可，但不能混用。

• 需要纯编译能力？选 @mdx-js/mdx。
• 使用 webpack 且想自动导入？选 @mdx-js/loader。
• 要在 React 中渲染？必须选 @mdx-js/react。

理解这三者的边界，能让你在面对复杂的文档系统或内容平台架构时，做出更清晰的技术决策。