Next.js水合错误求助：页面刷新时持续出现报错问题

报错根源 #

1. Link组件导入与使用错误：

   • 导入路径错误：使用了next/Link（大写L），正确路径应为next/link（小写l），导致服务器渲染时无法生成正确的<a>标签，客户端Hydrate时DOM结构不匹配，触发Expected server HTML to contain a matching <a> in <div>警告，进而引发Hydration失败。
   • 使用方式错误：Next.js Pages Router中，Link组件需包裹<a>标签，直接包裹<button>会导致服务器与客户端DOM结构差异。

2. 空值访问风险：当bannerData为空数组时，bannerData.length && bannerData[0]返回false，HeroBanner组件访问heroBanner.smallText等属性会抛出隐性错误，加剧Hydration问题。

3. 列表渲染不规范：products.map直接返回文本节点，未用HTML元素包裹，违反React渲染规则，可能导致DOM结构不稳定。

4. Sanity客户端配置问题：useCdn设置为字符串'true'，应为布尔值true，可能导致数据获取不一致。

修复步骤 #

1. 修正Link组件的导入与使用 #

导入修正

// 替换错误导入
import Link from 'next/link';

使用修正（二选一）

方案A：用<a>包裹按钮（符合Link组件规范）

// 在HeroBanner组件中修改按钮部分
<div>
  <Link href={`/product/${heroBanner?.product}`}>
    <a>
      <button type='button'>{heroBanner?.buttonText}</button>
    </a>
  </Link>
  {/* ...其他代码 */}
</div>

方案B：用useRouter实现按钮跳转（更适合按钮场景）

import { useRouter } from 'next/router';

const HeroBanner = ({ heroBanner }) => {
  const router = useRouter();

  const handleGoToProduct = () => {
    if (heroBanner?.product) {
      router.push(`/product/${heroBanner.product}`);
    }
  };

  return (
    {/* ...其他代码 */}
    <button type='button' onClick={handleGoToProduct}>
      {heroBanner?.buttonText}
    </button>
    {/* ...其他代码 */}
  );
};

2. 处理空值，避免属性访问错误 #

页面传入默认值

// Home页面中修改HeroBanner的props传递
<HeroBanner heroBanner={bannerData.length ? bannerData[0] : {}} />

组件内添加可选链保护

// HeroBanner组件中所有属性访问添加可选链
<p className='beats-solo'>{heroBanner?.smallText}</p>
<h3>{heroBanner?.midText}</h3>
<h1>{heroBanner?.discount}</h1>
<img 
  src={heroBanner?.image ? urlFor(heroBanner.image) : ''} 
  alt="headphones" 
  className="hero-banner-image"
/>

3. 规范列表渲染 #

给列表项包裹元素并添加稳定的key：

// Home页面中修改products渲染部分
<div className='products-container'>
  {products?.map((product) => (
    <div key={product._id} className='product-item'>
      {product.name}
    </div>
  ))}
</div>

4. 修正Sanity客户端配置 #

// client.js中修改useCdn配置
export const client = sanityClient({
  // ...其他配置
  useCdn: true, // 改为布尔值
});

验证 #

完成上述修改后，重启开发服务器，刷新页面即可消除Hydration错误与HTML匹配警告。

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