Next.js/MDX个人主页KaTeX公式被code标签包裹渲染异常修复求助

阿华AIGC实验室

2026-6-13

解决Next.js + MDX中KaTeX公式被错误包裹在<code>标签的问题

核心原因

代码高亮插件（如remark-prism/rehype-highlight）与remark-math/rehype-katex的处理顺序或规则冲突，导致数学公式被误识别为代码块。

解决方案

1. 强制调整插件执行顺序

确保remark-math在所有代码高亮的remark插件之前执行，rehype-katex在所有代码高亮的rehype插件之前执行。这样数学公式会被优先识别并转换为专用节点，后续代码高亮插件不会再将其当作代码处理。

以Next.js的MDX配置为例（next.config.js）：

const withMDX = require('@next/mdx')({
  extension: /\.mdx?$/,
  options: {
    // remark阶段：先处理数学公式，再处理代码高亮
    remarkPlugins: [
      require('remark-math'),
      require('remark-prism') // 或其他代码高亮remark插件
    ],
    // rehype阶段：先渲染KaTeX公式，再处理代码高亮
    rehypePlugins: [
      require('rehype-katex'),
      require('rehype-highlight') // 或其他代码高亮rehype插件
    ],
  },
});

module.exports = withMDX({
  pageExtensions: ['js', 'jsx', 'md', 'mdx'],
});

2. 自定义代码高亮插件，排除数学节点

如果调整顺序后问题仍存在，可以给代码高亮插件添加过滤规则，跳过已被识别为数学公式的节点。

以remark-prism为例，自定义插件过滤数学节点：

const remarkMath = require('remark-math');
const remarkPrism = require('remark-prism');
const { visit } = require('unist-util-visit');

// 自定义Prism插件，跳过math类节点
const customPrismPlugin = () => {
  return (tree) => {
    visit(tree, 'element', (node) => {
      // 识别remark-math生成的数学节点（通常带有math类）
      if (node.properties.className?.includes('math')) {
        return visit.SKIP; // 跳过该节点，不进行代码高亮处理
      }
    });
    // 执行原Prism插件逻辑
    return remarkPrism()(tree);
  };
};

// 配置MDX插件时使用自定义版本
const withMDX = require('@next/mdx')({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins: [remarkMath, customPrismPlugin],
    rehypePlugins: [require('rehype-katex')],
  },
});