Umi.js 4 中 Markdown 文件导入的配置与解决方案

背景介绍

Umi.js 是一个企业级前端应用框架，在从 Umi 3 升级到 Umi 4 的过程中，开发者可能会遇到 Markdown 文件导入行为变化的问题。本文将详细分析这一变化的原因，并提供多种解决方案。

问题现象

在 Umi 3 中，直接导入 Markdown 文件会得到文件的原始内容：

import md from './index.md';
console.log(md); // 输出 Markdown 源码

而在 Umi 4 中，同样的导入方式会返回文件的 URL 路径：

import md from './index.md';
console.log(md); // 输出带 publicPath 的路径

原因分析

这种变化源于 Umi 4 基于 Webpack 5 的重大升级。Webpack 5 引入了全新的 Asset Modules 概念，取代了传统的 loader 处理方式：

1. Webpack 5 默认将 Markdown 文件视为静态资源
2. 资源文件会被复制到输出目录并返回访问路径
3. 不再需要 url-loader/file-loader 等传统 loader

解决方案

方案一：使用 MDX 配置

如果需要渲染 Markdown 内容，可以配置 MDX 支持：

1. 安装 @umijs/mdx 插件
2. 在配置中启用 mdx 功能
3. 这种方式适合需要将 Markdown 渲染为 React 组件的场景

方案二：配置 Webpack 规则

如果只需要获取 Markdown 原始内容，可以通过 chainWebpack 修改配置：

export default {
  chainWebpack(config) {
    // 排除 Markdown 文件不被视为静态资源
    config.module.rule('asset').exclude.add(/\.md$/).end();
    
    // 添加 Markdown 文件处理规则
    config.module
      .rule('md')
      .test(/\.md$/)
      .type('asset/source'); // Webpack 5 原生方式
  }
}

方案三：使用传统 loader（兼容方案）

对于需要兼容旧配置的场景，可以使用 raw-loader：

export default {
  chainWebpack(config) {
    config.module
      .rule('md')
      .test(/\.md$/)
      .use('raw')
      .loader('raw-loader');
  }
}

最佳实践建议

1. 对于新项目，推荐使用 Webpack 5 的 asset/source 方式
2. 已有项目升级时，可以根据实际需求选择兼容方案
3. 如果需要 Markdown 渲染功能，MDX 是最完整的解决方案
4. 注意检查项目中其他静态资源的处理规则是否受到影响

总结

Umi 4 对静态资源的处理方式进行了现代化改进，理解这些变化有助于开发者更好地配置项目。通过合理选择上述方案，可以灵活应对不同场景下的 Markdown 文件处理需求。