NextJS自定义组件hydration异常：hydrateRoot报错及DOM重复求助

你遇到的报错和重复渲染问题，核心是服务端渲染出的HTML与客户端hydrateRoot时生成的虚拟DOM结构不匹配：

1. 服务端用ReactDOMServer.renderToString生成组件HTML，再通过Cheerio替换原始HTML中的macro标签，但Cheerio默认会自动补全标签、调整属性顺序，导致最终输出的HTML和客户端组件渲染的DOM结构存在差异。
2. React的hydration机制会严格校验服务端DOM和客户端虚拟DOM的一致性，一旦不匹配就会抛出报错，并触发重新渲染，这就是包裹div重复出现的原因。
3. 若macro组件在服务端和客户端的逻辑、渲染结果不一致（比如服务端组件缺少客户端特有的逻辑），也会加剧这种不匹配。

方案一：客户端动态替换（推荐，彻底避免不匹配问题） #

放弃服务端提前替换macro标签，改为客户端挂载后动态处理：

1. 服务端直接把带macro标签的原始HTML通过dangerouslySetInnerHTML渲染到页面，不做任何替换。
2. 页面组件中用useEffect在客户端完成替换逻辑：

   'use client';
   import { useEffect } from 'react';
   import { hydrateRoot } from 'react-dom/client';
   // 导入你的macro组件映射表
   import macroComponents from '@/components/macros';
   
   export default function Page({ rawHtml }) {
     useEffect(() => {
       // 找到所有macro标签
       const macroElements = document.querySelectorAll('macro');
       macroElements.forEach(el => {
         const alias = el.getAttribute('alias');
         const params = JSON.parse(el.getAttribute('params'));
         const Component = macroComponents[alias];
         
         if (Component) {
           // 创建容器替换原macro标签
           const container = document.createElement('div');
           el.parentNode.replaceChild(container, el);
           //  hydration渲染组件
           hydrateRoot(container, <Component {...params} />);
         }
       });
     }, []);
   
     return <div dangerouslySetInnerHTML={{ __html: rawHtml }} />;
   }
   

这种方式完全隔离服务端和客户端的渲染逻辑，不会出现DOM不匹配的问题，同时能保证客户端逻辑正常生效。

方案二：修复服务端与客户端渲染一致性 #

如果必须在服务端替换macro，要确保两端渲染结果完全一致：

1. 禁用Cheerio的自动格式化：初始化Cheerio时关闭标签补全、属性调整等特性，避免修改原始HTML结构：

   const cheerio = require('cheerio');
   const $ = cheerio.load(rawHtml, {
     xmlMode: true, // 保持标签原样，不自动补全
     decodeEntities: false, // 不转义HTML实体
     lowerCaseTags: false // 保留标签大小写
   });
   

2. 保证组件两端逻辑一致：服务端和客户端使用完全相同的组件代码，包括样式、属性处理、渲染逻辑，避免出现服务端渲染时缺少客户端特有的逻辑。
3. 独立容器hydrate：服务端替换macro时，给每个组件包裹带唯一ID的容器，并把参数存在data-*属性中：

   // 服务端处理逻辑
   const { v4: uuidv4 } = require('uuid');
   $('macro').each((_, el) => {
     const alias = $(el).attr('alias');
     const params = $(el).attr('params');
     const macroId = `macro-${uuidv4()}`;
     const Component = macroComponents[alias];
     const componentHtml = ReactDOMServer.renderToString(<Component {...JSON.parse(params)} />);
     $(el).replaceWith(`<div id="${macroId}" data-alias="${alias}" data-params="${params}">${componentHtml}</div>`);
   });
   

   客户端根据ID精准hydrate：

   'use client';
   import { useEffect } from 'react';
   import { hydrateRoot } from 'react-dom/client';
   import macroComponents from '@/components/macros';
   
   export default function Page({ processedHtml }) {
     useEffect(() => {
       const macroContainers = document.querySelectorAll('[id^="macro-"]');
       macroContainers.forEach(container => {
         const alias = container.dataset.alias;
         const params = JSON.parse(container.dataset.params);
         const Component = macroComponents[alias];
         hydrateRoot(container, <Component {...params} />);
       });
     }, []);
   
     return <div dangerouslySetInnerHTML={{ __html: processedHtml }} />;
   }
   

方案三：拆分渲染逻辑（适合布局灵活的场景） #

服务端不直接替换macro，而是提取macro的元数据，页面组件先渲染原始HTML，再单独渲染macro组件：

1. 服务端处理：解析原始HTML，提取所有macro的alias和params，同时移除原始HTML中的macro标签，把两个结果作为props传给页面。
2. 页面组件渲染：

   'use client';
   import macroComponents from '@/components/macros';
   
   export default function Page({ rawHtml, macros }) {
     return (
       <div>
         <div dangerouslySetInnerHTML={{ __html: rawHtml }} />
         {macros.map(({ id, alias, params }) => {
           const Component = macroComponents[alias];
           return <Component key={id} {...params} />;
         })}
       </div>
     );
   }
   

注：这种方式需要通过CSS定位等方式，保证macro组件渲染到正确的页面位置，适合macro位置不依赖原始HTML流的场景。

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