模板字面量引发Hydration错误的原因排查求助

问题场景 #

我有一个用于展示邮箱信息的组件，开发模式下运行正常，部署后页面显示也没问题，但会抛出多个Hydration错误：

export default function Email({ email, name }: EmailProps) {
  return (
    <li className="ml-6">
      {name ? `${name} <${email}>` : email}
    </li>
  );
}

经过测试发现，只要把模板字面量替换成多个独立字符串拼接的形式，Hydration错误就会消失：

export default function Email({ email, name }: EmailProps) {
  return (
    <li className="ml-6">
      {name ? (
        <> {name}{" <"}{email}{">"}</>
      ) : (
        email
      )}
    </li>
  );
}

补充：页面组件使用unstable_noStore()从数据库获取数据，仅在打包部署环境（本地Docker或GCP）出现错误，开发模式下无异常。

原因分析 #

Hydration错误的核心是服务端渲染的HTML与客户端Hydration生成的DOM结构不一致，这里的问题出在文本节点的结构差异：

• 使用模板字面量时，${name} <${email}>会生成单个文本节点，内容是合并后的完整字符串（比如"张三 <zhangsan@example.com>"）。
• 改用多个字符串拼接时，会生成多个独立的文本节点（分别对应name、" <"、email、">"）。

在生产打包过程中，Next.js的代码压缩工具（如Terser）会对单个文本节点做空格优化或字符处理，但多个文本节点的内容不会被合并压缩。这就导致服务端渲染的HTML文本节点结构，和客户端Hydration时生成的DOM节点结构不匹配，触发Hydration mismatch错误。

而开发模式下没有开启这些压缩优化，所以文本节点结构一致，不会报错。

解决办法 #

避免使用单个模板字面量生成包含特殊符号或多段拼接的文本，改用多字符串片段拼接（或用<>包裹），保证服务端和客户端生成的DOM节点结构完全一致，就能避免这类Hydration错误。

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