NextJS 14 <Image>组件触发Hydration错误排查求助

问题核心 #

这个 hydration 失败的问题，本质是服务端首次渲染的UI和客户端 hydration 阶段生成的UI不一致。热重载后恢复是因为热重载会触发客户端直接重新渲染，跳过了服务端与客户端的UI对比环节。

无需使用getStaticProps #

该问题和数据预获取逻辑无关，不用折腾getStaticProps，重点要解决服务端与客户端渲染时Image组件src的一致性问题。

具体修复方案 #

• 给image props设置默认值：避免服务端渲染时image为undefined，导致src变成/images/.jpg，和客户端后续拿到有效值后的src产生差异。修改组件定义：

  const Card = ({ title, text, link, image = 'default-placeholder', alt }) => {
    // ... 原有代码逻辑
  }
  

• 条件渲染Image组件：仅当image有有效值时再渲染图片，避免服务端渲染空src的图片节点：

  {image && (
    <Image
      src={`/images/${image}.jpg`}
      alt={alt}
      layout="intrinsic"
      width={150}
      height={150}
      className="card-img-top"
    />
  )}
  

• 改用静态导入图片（推荐）：如果图片是项目内的静态资源，直接用import导入后传给Card组件，Next.js会自动处理图片优化，彻底避免动态拼接src导致的渲染不一致：
  父组件中：

  import exampleImage from '/images/example.jpg'
  
  <Card 
    title="示例标题" 
    text="示例文本" 
    link="/example" 
    image={exampleImage} 
    alt="示例图片" 
  />
  

  Card组件中直接使用：

  <Image
    src={image}
    alt={alt}
    layout="intrinsic"
    width={150}
    height={150}
    className="card-img-top"
  />
  

关于'use client' #

这个问题不是客户端组件的范畴，加不加'use client'都无法解决核心的渲染不一致问题，没必要额外添加。

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