NextJS中Image组件渲染的Hydration问题求助

问题根源 #

Markdown解析时，图片会被自动包裹在<p>标签内，而你用<div>（块级元素）嵌套Next Image组件的写法违反了HTML规范——<p>标签不能包含块级元素。这导致服务端渲染生成的HTML结构，和客户端Hydration时的DOM结构不一致，最终触发Hydration错误。

解决方案 #

方案一：用rehype插件修改Markdown解析结构 #

通过rehype-wrap插件，将包含图片的<p>标签替换为自定义容器，避免块级元素嵌套问题：

1. 安装依赖：

npm install rehype-wrap

2. 配置react-markdown：

import ReactMarkdown from 'react-markdown';
import rehypeWrap from 'rehype-wrap';
import Image from 'next/image';

const markdownConfig = {
  rehypePlugins: [
    [
      rehypeWrap,
      {
        selector: 'p:has(img)', // 匹配包含img的p标签
        wrapper: 'div.image-wrapper', // 将p替换为自定义div
      },
    ],
  ],
  components: {
    img: ({ src, alt }) => (
      <div className="custom-image-style">
        <Image
          src={src}
          alt={alt || ''}
          fill
          className="object-cover"
        />
      </div>
    ),
  },
};

// 使用组件
<ReactMarkdown {...markdownConfig}>{yourMarkdownContent}</ReactMarkdown>

方案二：将外层容器换成行内块元素 #

把原来的<div>换成<span>，并通过CSS设置为块级显示，既符合HTML规范，又保留样式：

import ReactMarkdown from 'react-markdown';
import Image from 'next/image';

const markdownConfig = {
  components: {
    img: ({ src, alt }) => (
      <span className="custom-image-container" style={{ display: 'block', margin: '1.5rem 0' }}>
        <Image
          src={src}
          alt={alt || ''}
          width={800}
          height={500}
          className="rounded-lg object-cover"
        />
      </span>
    ),
  },
};

方案三：自定义p组件处理图片场景 #

直接拦截<p>组件的渲染，当p内仅包含图片时，替换为自定义容器：

import React from 'react';
import ReactMarkdown from 'react-markdown';
import Image from 'next/image';

const markdownConfig = {
  components: {
    p: ({ children }) => {
      // 判断子元素是否为单个img
      const isSingleImg = React.Children.count(children) === 1 
        && React.isValidElement(children) 
        && children.type === 'img';

      if (isSingleImg) {
        const { src, alt } = children.props;
        return (
          <div className="custom-image-style">
            <Image
              src={src}
              alt={alt || ''}
              fill
              className="object-cover"
            />
          </div>
        );
      }
      // 其他情况正常渲染p标签
      return <p>{children}</p>;
    },
  },
};

推荐方案 #

优先选择方案一或方案三，这两种方式更符合HTML规范，样式和结构的控制也更灵活，能从根源上避免Hydration冲突。

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