使用React Interweave库渲染HTML时出现运行时Hydration错误怎么办？

问题场景 #

开发React组件时，从包含HTML代码的字符串数组中获取数据，通过Interweave库的Markup组件循环渲染表格。页面能正常显示，但运行时触发Hydration错误，注释掉<li className={styles.listContent}>{<Markup content={i} />}</li>后错误消失。

相关代码 #

数据数组代码 #

export const RewardsFromInvestments = [
  "代币持有者可获得的净收益耕作奖励，将通过以下公式计算并定期发放至代币持有者账户：",
  `为明确起见，收益耕作奖励包括交易手续费收入和原生代币奖励收入产生的利润。收益耕作奖励分配如下：
  <table>
    <tr>
      <td>分配给代币持有者的交易手续费收入</td>
      <td>100%</td>
    </tr>
    <tr>
      <td>分配给ZaynFi的交易手续费收入</td>
      <td>0%</td>
    </tr>
    <tr>
      <td>分配给代币持有者的原生代币奖励</td>
      <td>80%</td>
    </tr>
     <tr>
      <td>分配给ZaynFi的原生代币奖励</td>
      <td>20%</td>
    </tr>
  </table>`,
];

动态列表渲染代码 #

<ol
  className={`list-[lower-roman] font-normal text-[16px]  pl-5 outside ${styles.listTerms}`}
>
  {RewardsFromInvestments.map((i) => (
    <li className={styles.listContent}>{<Markup content={i} />}</li>
  ))}
</ol>

解决方案 #

Hydration错误的核心原因是服务端渲染（SSR）/静态生成（SSG）时，服务端输出的HTML与客户端Hydration生成的DOM结构不匹配。针对Markup组件的场景，可通过以下方法解决：

1. 强制仅客户端渲染Markup #

给Markup组件添加noSSR属性，跳过服务端渲染阶段的HTML解析，仅在客户端生成DOM：

<li className={styles.listContent}>
  <Markup content={i} noSSR />
</li>

2. 规范HTML字符串格式 #

清理HTML字符串中的多余缩进、换行，避免服务端与客户端因格式化差异导致DOM结构不一致：

`为明确起见，收益耕作奖励包括交易手续费收入和原生代币奖励收入产生的利润。收益耕作奖励分配如下：<table><tr><td>分配给代币持有者的交易手续费收入</td><td>100%</td></tr><tr><td>分配给ZaynFi的交易手续费收入</td><td>0%</td></tr><tr><td>分配给代币持有者的原生代币奖励</td><td>80%</td></tr><tr><td>分配给ZaynFi的原生代币奖励</td><td>20%</td></tr></table>`

3. 延迟渲染至Hydration完成 #

通过useEffect在客户端Hydration完成后再渲染Markup组件，确保DOM仅在客户端生成：

import { useEffect, useState } from 'react';

// 组件内部状态
const [isHydrated, setIsHydrated] = useState(false);

useEffect(() => {
  setIsHydrated(true);
}, []);

// 渲染逻辑
<ol
  className={`list-[lower-roman] font-normal text-[16px]  pl-5 outside ${styles.listTerms}`}
>
  {RewardsFromInvestments.map((i) => (
    <li className={styles.listContent}>
      {isHydrated && <Markup content={i} />}
    </li>
  ))}
</ol>

4. 临时抑制Hydration警告（不推荐长期使用） #

若上述方法无效，可使用suppressHydrationWarning属性临时屏蔽警告，仅用于排查问题：

<li className={styles.listContent} suppressHydrationWarning>
  <Markup content={i} />
</li>

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