Next.js中RandomShape组件触发Hydration错误的解决咨询

问题背景 #

开发了一个RandomShape组件，预期每次页面重载时从列表中返回随机SVG组件，但该组件在客户端触发了Hydration错误。

相关代码 #

RandomShape组件初始代码

import React from "react";
import shapes, { getRandomShape } from "./icons";

function RandomShape (options) {

    if (options.random){
        const randomShape = getRandomShape(shapeType);
        shapeType = shapeType || randomShape.type;
        shapeIndex = randomShape.index;
    }
    const Shape = shapes[shapeType][shapeIndex]; // the jsx component mapped from object

    return <Shape {...options} />;
};

export default RandomShape;

图标配置文件代码

//./icons/index.tsx

import Star1 from "./stars/s_1";
import Star2 from "./stars/s_2";

const shapes =  {
    star: [Star1, Star2],
  // ... other shapes
};

export const getRandomShape = (shapeType: keyof typeof shapes) => {
    const keys = Object.keys(shapes);
    const type = shapeType ||  keys[ Math.floor(keys.length * Math.random())];
    const index = Math.floor(shapes[type].length * Math.random());
    return {
        type,
        index
    };
};

export default shapes;

调用组件的Header代码

'use client'
import RandomShape from './randomShape.jsx';

export default function Header(){

    return(
          <RandomShape />
    );
};

错误信息 #

Error: Hydration failed because the initial UI does not match what was rendered on the server.

Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering. 

尝试过的无效方案 #

尝试等待组件挂载后再渲染，但没有效果，修改后的代码如下：

function RandomShape (options) {
    let shapeType = options.type
    let shapeIndex = options.index
    const [Shape, setRenderedShape] = useState(null);

    useEffect(()=>{
      if (options.random || !(shapeType && shapeIndex)){
        const randomShape = getRandomShape(shapeType);
        shapeType = shapeType || randomShape.type;
        shapeIndex = randomShape.index;
      }
        const shape = shapes[shapeType][shapeIndex];
        setRenderedShape(shape);
    },[]) 
  
    if (!Shape) {
        return null;
    }
    return <Shape {...options} />;
};

修改后组件仅在重载后短暂变化，随后回到初始状态，仍触发Hydration错误。

解决方案 #

核心原因 #

Hydration错误本质是服务器端渲染内容与客户端首次渲染内容不一致。初始代码中，服务器端执行getRandomShape生成随机形状，客户端Hydration时会再次执行该逻辑，大概率生成不同形状，导致内容不匹配。修改后的代码虽用了useEffect，但初始返回null，与服务器端渲染的具体形状仍不匹配，因此报错。

正确修复方式 #

方式1：确保客户端与服务器初始渲染一致，挂载后替换为随机形状

import React, { useState, useEffect } from "react";
import shapes, { getRandomShape } from "./icons";

function RandomShape(options) {
  const [shapeComponent, setShapeComponent] = useState(null);

  useEffect(() => {
    let shapeType = options.type;
    let shapeIndex = options.index;

    if (options.random || !(shapeType && shapeIndex)) {
      const randomShape = getRandomShape(shapeType);
      shapeType = shapeType || randomShape.type;
      shapeIndex = randomShape.index;
    }

    const Shape = shapes[shapeType][shapeIndex];
    setShapeComponent(<Shape {...options} />);
  }, [options]);

  // 服务器端与客户端初始渲染返回相同占位，避免不匹配
  if (!shapeComponent) {
    return <div style={{ visibility: 'hidden' }}></div>;
  }

  return shapeComponent;
};

export default RandomShape;

方式2：服务器端用默认形状，客户端挂载后切换为随机形状

import React, { useState, useEffect } from "react";
import shapes, { getRandomShape } from "./icons";

function RandomShape(options) {
  const [isClient, setIsClient] = useState(false);
  let shapeType = options.type;
  let shapeIndex = options.index;

  useEffect(() => {
    setIsClient(true);
  }, []);

  // 客户端挂载后生成随机形状，服务器端与初始渲染用默认值
  if (isClient && (options.random || !(shapeType && shapeIndex))) {
    const randomShape = getRandomShape(shapeType);
    shapeType = shapeType || randomShape.type;
    shapeIndex = randomShape.index;
  }

  // 服务器端用第一个star作为默认，确保客户端初始渲染与服务器一致
  const defaultShape = shapes.star[0];
  const Shape = isClient ? shapes[shapeType][shapeIndex] : defaultShape;

  return <Shape {...options} />;
};

export default RandomShape;

方式3：将随机逻辑移至客户端组件中执行

因为Header已标记'use client'，可把随机逻辑移到Header里，确保仅在客户端执行：

'use client'
import React, { useState, useEffect } from 'react';
import RandomShape from './randomShape.jsx';
import { getRandomShape } from './icons';

export default function Header(){
  const [shapeProps, setShapeProps] = useState({});

  useEffect(() => {
    const randomShape = getRandomShape();
    setShapeProps({ type: randomShape.type, index: randomShape.index });
  }, []);

  return(
        <RandomShape {...shapeProps} />
  );
};

同时修改RandomShape组件，仅根据传入props渲染：

import React from "react";
import shapes from "./icons";

function RandomShape(options) {
  const { type = 'star', index = 0, ...rest } = options;
  const Shape = shapes[type][index];
  return <Shape {...rest} />;
};

export default RandomShape;

关键注意事项 #

• 避免服务器端与客户端执行不同的随机逻辑，确保Hydration阶段内容一致。
• 依赖客户端环境的操作（如Math.random()）需放在useEffect或客户端组件中执行。
• 若必须展示客户端随机内容，要么让服务器返回占位，要么让初始渲染与服务器一致，再在客户端切换。

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