Next.js+React侧边栏Hydration失败错误求助

问题描述 #

使用Next.js和React开发网站时，侧边栏在用户登录状态下会重复抛出3次以下错误：

• Error: Hydration failed because the initial UI does not match what was rendered on the server
• Warning: Expected server HTML to contain a matching <a> in <div>
• 单次触发：Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering

已使用Tailwind CSS，排除其影响；尝试过谷歌搜索同类问题、移除锚点内的div，均未解决；且无法将侧边栏放入_app页面。

侧边栏代码 #

import { MdSportsRugby } from "react-icons/md";
import { CiMusicNote1 } from "react-icons/ci";
import { IoMdSchool } from "react-icons/io";
import { IoIosCreate } from "react-icons/io";
import { MdAccountCircle } from "react-icons/md";
import { FaPaintBrush } from "react-icons/fa";
import { FaHome } from "react-icons/fa";

import { useContext } from "react";
import { UserContext } from "@/lib/context";

const SideBar = ({ house }) => {
  const { user, username } = useContext(UserContext);

  return (
    <>
      {!user && (
        <div
          className="fixed top-0 left-0 h-screen w-16 m-0 
          flex flex-col bg-gray-900 text-white shadow z-0 items-center"
        >
          <SideBarIcon
            icon={<FaHome size="28" />}
            text="Home"
            link="../"
            house={house}
          />

          <LineBreak />

          <SideBarIcon
            icon={<MdSportsRugby size="28" />}
            text="Sports"
            house={house}
          />
          <SideBarIcon
            icon={<CiMusicNote1 size="28" />}
            text="Music"
            house={house}
          />
          <SideBarIcon
            icon={<IoMdSchool size="28" />}
            text="Academia"
            house={house}
          />
          <SideBarIcon
            icon={<FaPaintBrush size="28" />}
            text="Art"
            house={house}
          />
        </div>
      )}

      {user && (
        <div
          className="fixed top-0 left-0 h-screen w-16 m-0 
            flex flex-col bg-gray-900 text-white shadow z-0 items-center"
        >
          <SideBarIcon
            icon={<FaHome size="28" />}
            text="Home"
            link="../"
            house={house}
          />

          <LineBreak />

          <SideBarIcon
            icon={<MdSportsRugby size="28" />}
            text="Sports"
            house={house}
          />
          <SideBarIcon
            icon={<CiMusicNote1 size="28" />}
            text="Music"
            house={house}
          />
          <SideBarIcon
            icon={<IoMdSchool size="28" />}
            text="Academia"
            house={house}
          />
          <SideBarIcon
            icon={<FaPaintBrush size="28" />}
            text="Art"
            house={house}
          />

          <LineBreak />

          <SideBarIcon
            icon={<IoIosCreate size="28" />}
            text="Create"
            house={house}
          />

          <SideBarIcon
            icon={<MdAccountCircle size="28" />}
            text="Account"
            house={house}
            link={`/${username}`}
          />
        </div>
      )}
    </>
  );
};

const SideBarIcon = ({ icon, text, link, house }) => (
  <a href={link}>
    <div className={house}>
      {icon}

      <span className="sidebar-tooltip group-hover:scale-100">{text}</span>
    </div>
  </a>
);

const LineBreak = () => {
  return (
    <div className="bg-stone-300 h-[0.1px] w-12 opacity-30 mt-3 mb-3"></div>
  );
};

export default SideBar;

用户上下文代码 #

import { createContext } from "react";
export const UserContext = createContext({ user: null, username: null });

解决方案 #

1. 解决服务端与客户端状态不一致问题 #

水合错误的核心原因是：服务端渲染时user为null，但客户端初始化时user已存在，导致前后渲染的侧边栏结构完全不匹配。通过useEffect延迟渲染依赖用户状态的内容，确保仅在客户端完成状态同步后再渲染：

import { useContext, useEffect, useState } from "react";
// 保留原有导入

const SideBar = ({ house }) => {
  const { user, username } = useContext(UserContext);
  const [isClient, setIsClient] = useState(false);

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

  // 客户端未初始化前返回空，避免服务端与客户端渲染差异
  if (!isClient) return null;

  return (
    <>
      {/* 保留原有侧边栏渲染逻辑 */}
      {!user && (...)}
      {user && (...)}
    </>
  );
};

2. 修复空链接导致的DOM不匹配 #

当SideBarIcon未传入link属性时，<a href={link}>会生成href="undefined"的无效锚点，这也会触发水合警告。修改组件逻辑，仅在有有效链接时渲染锚点：

const SideBarIcon = ({ icon, text, link, house }) => {
  const content = (
    <div className={house}>
      {icon}
      <span className="sidebar-tooltip group-hover:scale-100">{text}</span>
    </div>
  );

  return link ? <a href={link}>{content}</a> : content;
};

3. 优化侧边栏结构（可选） #

合并重复的侧边栏代码，减少结构差异风险，同时降低维护成本：

const SideBar = ({ house }) => {
  const { user, username } = useContext(UserContext);
  const [isClient, setIsClient] = useState(false);

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

  if (!isClient) return null;

  return (
    <div
      className="fixed top-0 left-0 h-screen w-16 m-0 
        flex flex-col bg-gray-900 text-white shadow z-0 items-center"
    >
      <SideBarIcon
        icon={<FaHome size="28" />}
        text="Home"
        link="../"
        house={house}
      />

      <LineBreak />

      <SideBarIcon
        icon={<MdSportsRugby size="28" />}
        text="Sports"
        house={house}
      />
      <SideBarIcon
        icon={<CiMusicNote1 size="28" />}
        text="Music"
        house={house}
      />
      <SideBarIcon
        icon={<IoMdSchool size="28" />}
        text="Academia"
        house={house}
      />
      <SideBarIcon
        icon={<FaPaintBrush size="28" />}
        text="Art"
        house={house}
      />

      {/* 仅登录状态下渲染额外按钮 */}
      {user && (
        <>
          <LineBreak />
          <SideBarIcon
            icon={<IoIosCreate size="28" />}
            text="Create"
            house={house}
          />
          <SideBarIcon
            icon={<MdAccountCircle size="28" />}
            text="Account"
            house={house}
            link={`/${username}`}
          />
        </>
      )}
    </div>
  );
};

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