Next.js集成MDX数学插件后LaTeX公式后出现纯文本重复问题

问题根因 #

该问题属于插件兼容/配置错误导致的AST节点重复序列化：行内公式被rehype-katex渲染为HTML节点后，原公式对应的文本节点未被正确从AST树中移除，最终被重复输出为纯文本。aligned块级公式环境走独立的块级节点处理逻辑，不会触发该行内节点处理bug，因此可以临时规避问题。

修复方案（按优先级排序） #

• 固定兼容版本，规避已知版本兼容bug
  目前Next.js 13/14 App Router、Pages Router搭配next-mdx-remote@4.x/@next/mdx时，remark-math@6.x版本存在ESM导出逻辑兼容问题，会直接触发该重复bug，直接降级到稳定兼容版本即可：

  # 先卸载现有不兼容版本
  npm uninstall remark-math rehype-katex
  # 安装经过兼容验证的版本组合
  npm install remark-math@5.1.1 rehype-katex@6.0.3
  

  非必要不要升级remark-math到6.x以上版本。
• 修正插件配置顺序，避免节点重复处理
  插件配置必须严格遵循「remark插件归remark数组、rehype插件归rehype数组，math类插件放在同类型插件最前」的规则，错误的顺序会导致节点被多次处理。正确配置示例如下：

  import { MDXRemote } from 'next-mdx-remote/rsc' // 或pages路由对应导入
  import remarkMath from 'remark-math'
  import rehypeKatex from 'rehype-katex'
  // katex的CSS全局只引入1次，不要在layout和组件中重复引入
  import 'katex/dist/katex.min.css'
  
  export default function MDXRenderer({ source }) {
    return (
      <MDXRemote
        source={source}
        options={{
          mdxOptions: {
            remarkPlugins: [remarkMath], // remark-math必须放在remark插件数组
            rehypePlugins: [rehypeKatex], // rehype-katex必须放在rehype插件数组
          }
        }}
      />
    )
  }
  

  禁止将rehype-katex放入remark插件数组，也禁止将remark-math放入rehype插件数组。
• 特殊场景兼容：必须使用高版本remark-math时的去重方案
  如果项目其他插件依赖必须使用remark-math@6.x及以上版本，可以在rehype插件队列末尾新增自定义去重插件，过滤重复的文本节点：

  import { visit } from 'unist-util-visit'
  
  const rehypeCleanDuplicateMathText = () => (tree) => {
    visit(tree, 'element', (node, index, parent) => {
      // 匹配katex渲染完成的行内公式节点
      if (node.tagName === 'span' && node.properties?.className?.includes('katex')) {
        const nextNode = parent.children[index + 1]
        // 移除紧跟在公式节点后、内容匹配公式文本的重复节点
        if (nextNode?.type === 'text' && nextNode.value.trim().match(/^[\d\w+\-*/^()=]+$/)) {
          parent.children.splice(index + 1, 1)
        }
      }
    })
  }
  
  // 配置时放到rehypePlugins数组最后一位
  // rehypePlugins: [rehypeKatex, rehypeCleanDuplicateMathText]
  

• 排查冲突插件
  检查项目中是否同时引入了其他LaTeX渲染类插件（如rehype-mathjax、remark-katex），多插件重复处理数学公式节点也会触发文本重复问题，保留一个渲染链路即可。

验证 #

使用测试用例验证修复效果：

# Hello

My name $x^2+2x+1$

1. dd
2. aa
3. aaaaaa

修复后行内公式后方不会再出现重复的纯文本内容，无需强制使用aligned块级环境。

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