Next.js + MDX-Bundler换行包裹子组件时出现水化错误

问题场景 #

使用Next.js + MDX-Bundler开发时，MDX中引入基础组件的两种写法可正常运行：

Mdx is a great <Component>format and I like it a lot</Component>.

Mdx is a great 
<Component>format 
and I like it a 
lot</Component>.

但将组件标签单独换行、子内容置于中间的类代码对齐格式，会触发水化不匹配错误：

Mdx is a great 

<Component>
format and I like it a lot
</Component>.

错误提示：

Error: Hydration failed because the initial UI does not match what was rendered on the server.

该问题仅出现在部分组件上，导致无法正常使用Prettier格式化MDX内容，影响开发效率。

原因分析 #

核心问题是MDX在服务端与客户端对换行/空白字符的解析逻辑不一致：当组件标签单独换行时，服务端渲染可能生成额外的空白节点（如\n或空格），而客户端水化时解析出的DOM结构与服务端存在差异，触发React的水化校验机制报错。

部分组件不受影响的原因是：块级组件（如<div>）的浏览器会自动忽略多余空白，不会产生可见的结构差异；而对空白敏感的内联组件、纯文本容器，多余换行/空格会被渲染为可见空白或<br>标签，直接导致DOM结构不匹配。

解决办法 #

1. 统一MDX解析的空白处理 #

在mdx-bundler配置中添加remark或rehype插件，标准化空白字符的处理逻辑，确保服务端与客户端解析结果一致。示例配置：

import { bundleMDX } from 'mdx-bundler';
import remarkNormalize from 'remark-normalize';

const result = await bundleMDX({
  source: yourMDXContent,
  mdxOptions(options) {
    options.remarkPlugins = [...(options.remarkPlugins ?? []), remarkNormalize];
    return options;
  },
});

2. 给敏感组件添加水化忽略属性 #

针对容易触发错误的组件，添加suppressHydrationWarning属性，让React忽略该组件的水化差异（仅适合确认差异不影响功能的场景）：

<Component suppressHydrationWarning>
  format and I like it a lot
</Component>

3. 自定义Prettier规则适配MDX #

修改Prettier的MDX格式化规则，避免组件标签被单独换行。在.prettierrc中配置：

{
  "plugins": ["prettier-plugin-mdx"],
  "mdxSingleQuote": true,
  "printWidth": 80,
  "proseWrap": "never"
}

通过规则强制组件与文本保持在合适行内，避免不必要的换行。

4. 检查组件的SSR兼容性 #

排查出问题的组件，确保其在服务端与客户端的渲染输出完全一致。若组件依赖客户端特有API（如window），需用useEffect延迟执行相关逻辑，或使用Next.js的dynamic导入并禁用SSR：

import dynamic from 'next/dynamic';

const Component = dynamic(() => import('../components/Component'), { ssr: false });

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