Next.js中MDX博客rehype-slug未给标题添加ID问题排查

可能的原因及排查步骤 #

1. 检查MDX文件的标题写法 #

rehype-slug仅识别原生Markdown标题语法（如## Second heading），如果你的MDX中用了自定义标题组件（比如<Heading level={2}>Second heading</Heading>），插件无法识别并生成ID。确保使用标准Markdown标题格式：

## Second heading

2. 验证依赖版本兼容性 #

@next/mdx与rehype-slug版本不匹配可能导致功能失效，执行命令更新到兼容版本：

npm update @next/mdx rehype-slug rehype-autolink-headings

3. 排查插件执行顺序或冲突 #

rehype插件按数组顺序执行，确保没有其他rehype插件在rehype-slug之前修改、移除标题元素。若有其他插件，调整顺序让rehype-slug优先执行。

4. 清除Next.js缓存并重启服务 #

开发缓存可能导致配置未生效，按以下步骤操作：

• 停止当前开发服务器
• 删除项目根目录下的.next文件夹
• 重新启动服务器：npm run dev

5. 检查自定义MDX组件的属性传递 #

如果用useMDXComponents自定义了标题组件，需确保组件传递了所有原生props（包括rehype-slug生成的id）：

import { useMDXComponents } from '@mdx-js/react'

export function useCustomMDXComponents() {
  const components = useMDXComponents()
  return {
    ...components,
    h2: (props) => <h2 {...props}>{props.children}</h2>,
  }
}

在MDX布局组件中使用该自定义组件集合，确保ID属性被正确传递到DOM元素。

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