Next.js App Router中Remark与Rehype转换MDX失效及适配求助

插件失效问题排查与修复 #

1. 文件路由（/example）场景 #

• remark-toc失效：检查next.config.mjs中的MDX配置，确保remarkPlugins数组明确包含remark-toc，并配置正确参数（如指定生成TOC的标题层级）。示例配置：

// next.config.mjs
import createMDX from '@next/mdx'

const withMDX = createMDX({
  options: {
    remarkPlugins: [require('remark-toc')],
    rehypePlugins: [],
  },
})

export default withMDX({
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
})

• 自定义React组件无法运行：确认mdx-components.tsx正确导出组件映射，且MDX文件中使用的组件名称与映射一致。同时在App Router环境下，确保MDX页面正确引入并使用useMDXComponents传递自定义组件。

2. 动态路由（/posts/[slug]）场景 #

所有插件失效的核心原因是手动编译MDX时未传入插件配置，修复步骤：

1. 在lib/posts.ts的MDX编译逻辑中，明确传入remarkPlugins和rehypePlugins：

// lib/posts.ts
import { compile } from '@mdx-js/mdx'
import remarkToc from 'remark-toc'
import rehypePrettyCode from 'rehype-pretty-code'

export async function compileMdx(content: string) {
  return compile(content, {
    remarkPlugins: [remarkToc],
    rehypePlugins: [[rehypePrettyCode, {
      // rehype-pretty-code配置，如主题、行号等
      theme: 'github-dark',
    }]],
    outputFormat: 'function-body',
  })
}

2. 在app/posts/[slug]/page.tsx中渲染编译结果时，确保传递正确的MDX组件上下文，避免插件处理后的内容无法正常渲染。

数据库适配方案 #

可以无缝将getBlogPosts()适配为从数据库获取内容，无需大幅修改现有代码，具体步骤：

1. 替换数据读取逻辑：把原本读取本地blogposts文件夹的fs操作，替换为数据库查询（如Prisma、MongoDB等），从数据库获取MDX内容、slug、文章元数据（标题、日期等）。
2. 保持返回结构一致：修改后的getBlogPosts()必须返回和原函数完全相同的数据结构（比如每个文章对象包含slug、metadata、content字段），这样上层的路由生成、页面渲染代码无需改动。
3. 复用编译逻辑：数据库存储原始MDX字符串的话，直接复用现有的MDX编译函数，将本地文件内容替换为数据库查询结果即可。
4. 缓存对齐：给数据库查询添加Next.js缓存配置（如cache: 'force-cache'），和本地文件读取的缓存行为保持一致，保证性能。

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