Next.js中使用Shadcn Dialog组件出现Hydration Error问题求助

核心原因 #

Shadcn Dialog组件内部依赖浏览器环境的API（如DOM操作、Portal）或客户端专属状态，当你直接在服务端渲染阶段设置isOpen={true}时，服务端生成的HTML与客户端hydrate时的UI会出现不一致，触发Hydration错误。

解决方案 #

1. 延迟客户端渲染模态框 #

通过useState和useEffect，让服务端渲染时模态框处于关闭状态，客户端完成hydrate后再打开：

// 修改SetupPage组件
import { useState, useEffect } from 'react';
import { Modal } from "@/components/ui/modal";

const SetupPage = () => {
  const [isModalOpen, setIsModalOpen] = useState(false);

  useEffect(() => {
    // 客户端挂载后触发打开
    setIsModalOpen(true);
  }, []);

  return (
    <div className="p-4">
      <Modal 
        title="Test" 
        description="Test Desc" 
        isOpen={isModalOpen} 
        onClose={() => setIsModalOpen(false)}
      >
        Children
      </Modal>
    </div>
  );
}

export default SetupPage;

2. 禁用Modal组件的SSR渲染 #

使用Next.js的dynamic导入，让Modal仅在客户端渲染：

// 在SetupPage中调整Modal的导入方式
import dynamic from 'next/dynamic';

const Modal = dynamic(() => import('@/components/ui/modal'), {
  ssr: false,
  loading: () => null // 可选：渲染加载占位
});

const SetupPage = () => {
  return (
    <div className="p-4">
      <Modal 
        title="Test" 
        description="Test Desc" 
        isOpen 
        onClose={() => {}}
      >
        Children
      </Modal>
    </div>
  );
}

export default SetupPage;

3. 同步Dialog状态逻辑 #

修正Modal组件的状态回调，确保父组件状态与Dialog内部状态一致：

// 修改Modal组件的状态处理逻辑
export const Modal: React.FC<ModalProps> = ({
  title,
  description,
  isOpen,
  onClose,
  children
}) => {
  const handleOpenChange = (open: boolean) => {
    if (!open) onClose();
  };

  return ( 
    <Dialog open={isOpen} onOpenChange={handleOpenChange}>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>{title}</DialogTitle>
          <DialogDescription>{description}</DialogDescription>
        </DialogHeader>
        <div>{children}</div>
      </DialogContent>
    </Dialog>
  );
};

关键注意点 #

• 服务端无法模拟浏览器交互状态，避免在SSR阶段渲染需要客户端交互的组件（如模态框、弹出层）。
• 始终确保服务端与客户端的初始渲染DOM结构一致，减少Hydration不匹配的场景。

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