NextJS 13（App Router）使用Modal组件时Hydration失败错误求助

问题背景 #

在NextJS 13 App Router模式+SRC文件夹结构下，使用React-Bootstrap的Modal组件时，UI显示正常但控制台抛出以下错误：

Error: Hydration failed because the initial UI does not match what was rendered on the server.
Warning: Expected server HTML to contain a matching <div> in <body>.

尝试将Modal放在layout.tsx、Provider、页面组件等不同位置，用div或空标签包裹均无效，且Modal的DOM始终渲染在body标签之后，而非组件所在位置，干净的NextJS 13骨架项目中测试也会出现相同问题。

相关代码：
layout.tsx：

...
return (
    <html lang="en">
      <body className="min-h-screen">
        <Providers>{children}</Providers>
        {/* Allow more height for mobile menu on mobile */}
        <div className="h-40 md:hidden" />
      </body>
    </html>
  );

page.jsx：

import Modal from "react-bootstrap/Modal";
export default function Home() {
 return (
    <>
      <SomeComponents/>
<Modal show={true}>Text</Modal>
    </>
  );
}

问题原因 #

React-Bootstrap的Modal默认使用React Portal将DOM元素挂载到body标签的末尾，而NextJS服务端渲染时，Modal的代码会被输出在组件所在的位置，客户端渲染时Portal会将Modal的DOM移动到body后面，导致服务端与客户端的DOM结构不匹配，触发Hydration错误。

解决方案 #

方法1：禁用Modal的Portal功能 #

通过设置Modal的container={false}，让Modal直接渲染在组件所在位置，避免Portal导致的DOM位置差异：

import Modal from "react-bootstrap/Modal";

export default function Home() {
  return (
    <>
      <SomeComponents />
      <Modal show={true} container={false}>
        Text
      </Modal>
    </>
  );
}

优点：实现简单；缺点：Modal会继承父组件的样式和布局限制，可能影响显示效果。

方法2：将Modal放在客户端组件中 #

NextJS App Router默认组件为服务端组件，而Portal是客户端操作。给包含Modal的页面/组件添加'use client'指令，标记为客户端组件，让服务端不渲染这部分内容，客户端渲染时Portal正常工作：

'use client';
import Modal from "react-bootstrap/Modal";

export default function Home() {
  return (
    <>
      <SomeComponents />
      <Modal show={true}>
        Text
      </Modal>
    </>
  );
}

优点：符合NextJS App Router的组件模型，Portal功能正常使用；缺点：整个页面变为客户端组件，无法使用服务端组件的特性（如数据预取），如果页面其他部分不需要客户端交互，可将Modal单独抽成客户端组件。

方法3：自定义Modal挂载容器 #

在layout中添加专门的Modal容器，让Modal挂载到该容器内，确保服务端与客户端的DOM结构一致：

1. 修改layout.tsx，添加容器：

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className="min-h-screen">
        <Providers>{children}</Providers>
        <div className="h-40 md:hidden" />
        {/* 新增Modal挂载容器 */}
        <div id="modal-root" />
      </body>
    </html>
  );
}

2. 在客户端组件中指定该容器：

'use client';
import Modal from "react-bootstrap/Modal";
import { useRef, useEffect } from 'react';

export default function Home() {
  const modalContainer = useRef(null);

  useEffect(() => {
    modalContainer.current = document.getElementById('modal-root');
  }, []);

  return (
    <>
      <SomeComponents />
      <Modal show={true} container={modalContainer.current}>
        Text
      </Modal>
    </>
  );
}

优点：既保留Portal的特性，又避免Hydration错误，适合多Modal场景；缺点：需要额外配置容器，代码稍复杂。

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