解决90%开发者踩坑！Umi.js MPA模式集成MDX完全指南

解决90%开发者踩坑！Umi.js MPA模式集成MDX完全指南

【免费下载链接】umi A framework in react community ✨ 项目地址: https://gitcode.com/GitHub_Trending/um/umi

在Umi.js的多页面应用（MPA）开发中，MDX（Markdown + JSX）文件的使用常常让开发者头疼不已。本文将从环境配置、路由映射到性能优化，系统性梳理MPA模式下使用MDX的核心要点，帮助你避开常见陷阱，实现内容与交互的无缝融合。

MPA模式目录结构解析

Umi.js的MPA模式通过文件系统自动生成路由，与传统SPA（单页面应用）有显著差异。典型的MPA目录结构如下：

examples/mpa/
├── layouts/           # 布局组件
│   ├── basic.tsx      # 基础布局
│   └── foo.tsx        # 自定义布局
├── pages/             # 页面目录（自动生成路由）
│   ├── bar/
│   │   └── index.tsx  # /bar路由页面
│   └── foo/
│       └── config.json # 页面配置
└── templates/
    └── default.html   # HTML模板

关键文件说明：

• 布局文件：examples/mpa/layouts/basic.tsx 定义页面公共结构
• 页面入口：examples/mpa/pages/bar/index.tsx 对应/bar路由
• 配置文件：examples/mpa/pages/foo/config.json 页面级配置

MDX文件集成核心步骤

1. 安装必要依赖

在MPA项目根目录执行以下命令安装MDX处理器和相关插件：

npm install @umijs/plugin-mdx @mdx-js/react --save

2. 配置Umi支持MDX

在项目配置文件（通常是config.ts或.umirc.ts）中添加MDX插件：

export default {
  plugins: ['@umijs/plugin-mdx'],
  mpa: {}, // 启用MPA模式
  routes: [
    { 
      path: '/docs', 
      component: './pages/docs/index.mdx', // 直接指定MDX文件为路由组件
      layout: false // 可选：禁用全局布局
    }
  ]
}

3. 创建MDX页面

在pages目录下创建MDX文件，例如pages/docs/index.mdx：

import { Button } from 'antd';

# Hello MDX in Umi MPA

这是一个包含React组件的Markdown文件：

<Button type="primary">点击我</Button>

## 代码示例

```tsx
function Demo() {
  return <div>MPA模式下的MDX组件</div>
}

## 常见问题与解决方案

### 路由映射异常

**问题**：MDX文件未被正确识别为路由页面。  
**解决**：确保MDX文件位于`pages`目录下，且文件名遵循`index.mdx`命名规范。Umi会自动将`pages/docs/index.mdx`映射为`/docs`路由。

### 布局样式丢失

**问题**：MDX页面未应用全局布局样式。  
**解决**：在MDX文件头部添加布局声明：

```mdx
/**
 * layout: basic
 */

# 带布局的MDX页面

这里的basic对应examples/mpa/layouts/basic.tsx布局组件。

组件导入失败

问题：MDX中导入React组件时报错。
解决：确保在Umi配置中添加JSX支持：

// config.ts
export default {
  esbuild: {
    jsxInject: 'import React from \'react\'',
  },
}

性能优化建议

1. 启用按需加载

在MPA模式下，通过路由级别按需加载MDX内容：

// config.ts
export default {
  dynamicImport: {
    loading: '@/components/Loading',
  },
}

2. 静态生成优化

对于纯展示型MDX页面，使用Umi的SSG（静态站点生成）功能：

umi build --ssg

生成的静态文件位于dist目录，可直接部署到CDN。

最佳实践总结

1. 目录规范：始终将MDX文件放在pages目录下，保持与路由结构一致
2. 配置分离：复杂页面配置使用config.json单独管理
3. 样式隔离：通过CSS Modules避免MDX内容样式污染全局
4. 版本控制：定期同步官方示例examples/mpa中的最佳实践

通过以上方法，你可以在Umi.js MPA模式中高效使用MDX文件，兼顾内容编辑的便捷性和应用性能。更多高级用法可参考官方文档docs/README.md和社区示例examples/mpa。

【免费下载链接】umi A framework in react community ✨ 项目地址: https://gitcode.com/GitHub_Trending/um/umi