升级Next.js 12至14后遇Hydration错误，如何保留SSR解决？

问题概述 #

将Next.js应用从12版本升级到14版本，已通过codemod完成所有必要变更，但仍存在两类Hydration错误：

1. 第一类错误：

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

Warning: Expected server HTML to contain a matching <button> in <div>.

See more info here: https://nextjs.org/docs/messages/react-hydration-error

2. 第二类错误：

Unhandled Runtime Error
Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.

已修复<div>嵌套在<p>标签内的非法结构问题，但仍无法定位根源。已知通过设置动态组件ssr: false或useEffect判断客户端渲染可规避错误，但希望保留服务端渲染，需针对性解决。

排查与解决方法 #

1. 定位DOM不匹配的核心原因 #

针对第一类<button>与<div>不匹配的错误：

• 检查客户端API依赖：组件顶层或状态初始化阶段是否直接使用window、document等客户端专属API？比如在useState初始值中依赖window.innerWidth，会导致服务端渲染无对应值，客户端渲染时生成不同DOM结构。
• 延迟客户端逻辑执行：用useEffect包裹客户端特有的状态更新或DOM操作，确保服务端与客户端初始渲染结构一致。示例代码：

import { useState, useEffect } from 'react';

function ResponsiveButton() {
  const [showButton, setShowButton] = useState(false);

  useEffect(() => {
    // 仅客户端执行的逻辑
    setShowButton(window.innerWidth > 768);
  }, []);

  return (
    <div>
      {showButton && <button>操作按钮</button>}
    </div>
  );
}

2. 补全Suspense边界处理异步渲染 #

针对第二类无Suspense边界导致的降级渲染：

• 包裹异步组件/数据请求：Next.js 13+ App Router默认支持Suspense，Pages Router需手动为异步数据加载的组件添加Suspense边界，避免错误扩散。示例：

import { Suspense } from 'react';
import AsyncDataComponent from '../components/AsyncDataComponent';

export default function HomePage() {
  return (
    <div>
      <Suspense fallback={<div>数据加载中...</div>}>
        <AsyncDataComponent />
      </Suspense>
    </div>
  );
}

• 校验数据一致性：检查getServerSideProps/getStaticProps返回的数据，确保客户端不会在初始渲染阶段额外发起请求导致DOM不匹配；App Router中使用async/await的组件必须处于Suspense边界内。

3. 排查第三方组件兼容性 #

升级后部分第三方组件可能未适配Next.js 14的SSR逻辑：

• 定位问题组件：逐一排查近期引入或升级的第三方UI组件，确认是否存在组件内部直接调用客户端API且未做服务端兼容的情况（如部分图表、富文本编辑器）。
• 兼容改造：若组件无官方SSR方案，可封装一层，用useEffect初始化客户端专属配置，避免服务端渲染时生成异常DOM；若必须禁用该组件SSR，可局部设置dynamic导入的ssr: false，不影响全局SSR。

4. 验证HTML结构合法性 #

除已修复的<div>嵌套<p>问题，还需检查其他非法HTML结构：

• 比如<a>嵌套<a>、<ul>直接包含非<li>元素等，浏览器会自动修正这类结构，导致服务端渲染的HTML与客户端hydrate后的DOM不一致。
• 用HTML验证工具检查页面最终渲染的结构，修复所有非法嵌套。

5. 启用调试日志精准定位 #

开启Next.js调试模式，获取更详细的错误栈：

• 在next.config.js中添加配置：

module.exports = {
  logging: {
    fetches: {
      fullUrl: true,
    },
  },
};

• 查看浏览器控制台的错误详情，定位到具体组件文件和行号，快速锁定问题代码。

内容的提问来源于stack exchange，提问作者Shivakant Upendra Shukla