迁移React应用至NextJS时出现Hydration水合错误如何解决？

报错由两个问题共同触发：

1. Next.js Pages Router 下 Suspense 与 next/dynamic 的兼容bug：Next.js 13之前的Pages Router对React 18 Suspense的服务端渲染支持不完整，给next/dynamic开启suspense: true后，把多个动态加载组件放在同一个Suspense边界下时，服务端输出的DOM结构和客户端首次hydration的结构会出现节点层级/数量偏差。当组件返回div、h2、p这类块级标签时，浏览器会自动对非法DOM嵌套做纠错修正，直接放大结构不匹配问题触发报错；如果返回纯文本，文本节点不会触发块级布局纠错，所以不会抛错，这就是为什么你用标签包裹文本就报错、直接返回文本就正常的原因。
2. Tag组件存在无效逻辑：你引入了react-intersection-observer的useInView钩子，解构出ref但没有绑定到任何渲染的DOM节点上，这部分虽然不是报错核心诱因，但部分老版本的react-intersection-observer会在服务端渲染时注入额外注释节点，会进一步加剧DOM结构不匹配的问题。

按优先级操作即可修复：

• 第一优先级：移除手动添加的Suspense边界和dynamic的suspense配置，这是成本最低的修复方案。Pages Router下的next/dynamic原生支持加载状态配置，不需要手动套Suspense，修改index.js代码如下：

import React, { Fragment } from 'react';
import dynamic from 'next/dynamic';
import Loading from '../components/shared/Loading';

const AboutMe = dynamic(() => import('../components/AboutMe'), { loading: () => <Loading /> });
const Contact = dynamic(() => import('../components/Contact'), { loading: () => <Loading /> });

function App() {
  return (
    <Fragment>
      <AboutMe/>
      <Contact/>
    </Fragment>
  );
}

export default App;

• 第二优先级：修复Tag组件的无效逻辑，要么把useInView返回的ref绑定到实际渲染的DOM节点上，要么直接删除未使用的钩子逻辑，修改Tag.js代码如下：

import React from 'react';
import { useInView } from 'react-intersection-observer';
import Link from 'next/link';

function Tag(props) {
  const { ref, inView } = useInView({
    threshold: .5,
    triggerOnce: true
  });

  return (
    <Link href={props.href} passHref>
      <a ref={ref}>
        {props.children}
      </a>
    </Link>
  )
}

export default Tag;

• 如果业务场景必须使用Suspense，做两个适配即可：
  • 升级Next.js到13.4+版本并使用App Router，App Router对React Suspense的服务端渲染支持完整，不会出现结构不匹配问题
  • 给每个动态加载的组件单独包裹Suspense边界，不要把多个dynamic组件放在同一个Suspense下

如果上述修改完成后仍有水合报错，直接检查两个高频触发点：

• 检查pages/_app.js、pages/_document.js中的DOM结构，不要把页面组件、全局布局放在<p>、<span>这类行内标签内，行内标签嵌套块级标签会触发浏览器自动修正DOM结构，100%触发水合错误
• 检查是否有组件在首次渲染时直接读取window、document等浏览器专属API，这类逻辑要放到useEffect中执行，或者增加typeof window !== 'undefined'的判断，避免服务端和客户端首次渲染输出不一致。

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