gatsby-plugin-mdx无法通过require加载remark、rehype类插件问题求助

问题原因 #

你遇到的ERR_REQUIRE_ESM报错是因为rehype-slug、remark-math、rehype-katex这类统一生态的插件最新版已全面切换为纯ESM模块，仅支持import语法导入，不支持CommonJS的require()语法导入，而Gatsby v3默认的配置文件为CommonJS格式，直接用require加载就会触发报错。

可行解决方案 #

方案1：降级插件到CommonJS兼容版本 #

无需改动现有配置格式，适合不想调整项目架构的场景，各插件对应的最后一个CommonJS版本如下：

• rehype-slug：4.0.1
• rehype-katex：5.0.0
• remark-math：5.0.0

操作步骤：

1. 卸载当前安装的高版本插件：

npm uninstall rehype-slug rehype-katex remark-math

2. 安装指定兼容版本：

npm install rehype-slug@4.0.1 rehype-katex@5.0.0 remark-math@5.0.0

注意：安装完成后建议锁死插件版本，删除package.json中对应版本号前的^符号，避免自动升级到ESM版本再次触发报错。原有gatsby-config.js的require配置无需修改，可直接正常运行。

方案2：切换项目为ESM模式 #

如果需要使用最新版的插件，可将Gatsby配置调整为ESM格式，操作步骤：

1. 打开项目根目录的package.json，添加配置项"type": "module"
2. 将gatsby-config.js内容替换为ESM语法：

import rehypeSlug from 'rehype-slug'
import remarkMath from 'remark-math'
import rehypeKatex from 'rehype-katex'

export default {
  siteMetadata: {
    siteUrl: "https://www.yourdomain.tld",
    title: "test Website",
  },
  plugins: [
    {
      resolve: "gatsby-plugin-mdx",
      options:{
        rehypePlugins: [
          rehypeSlug,
          rehypeKatex
        ],
        remarkPlugins: [
          remarkMath
        ]
      }
    }
  ],
};

修改完成后重新运行gatsby develop即可正常加载最新版插件。

注意：如果你的项目中存在大量使用require语法的CommonJS文件，优先选择方案1，避免全局修改为ESM模式后引发其他兼容问题。

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