Chakra UI与NextJS水合失败问题求助

错误信息 #

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

Warning: Did not expect server HTML to contain a <a> in <div>.

问题分析 #

该错误表明服务器端渲染的HTML结构与客户端水合生成的DOM结构不一致——服务器端的<div>中出现了<a>标签，但客户端渲染的结构不符合这个预期。结合你的代码来看，问题出在NavBar组件中Chakra UI Link与Next.js NextLink的搭配方式上，这种配置在SSR场景下易导致渲染输出不一致。

修复方案 #

替换Chakra UI Link的as属性用法，改用Next.js官方推荐的嵌套方式，确保服务器与客户端渲染结构完全一致：

修改链接组件代码 #

// 导入所需组件
import NextLink from 'next/link';
import { Link as ChakraLink } from '@chakra-ui/react';

// 重构body内容
const body = (
  <>
    <NextLink href='/login' passHref>
      <ChakraLink mr={2}>login</ChakraLink>
    </NextLink>
    <NextLink href='/register' passHref>
      <ChakraLink mr={2}>register</ChakraLink>
    </NextLink>
  </>
);

原因说明 #

用NextLink包裹ChakraLink并添加passHref属性，是Chakra UI与Next.js集成的标准方案：既能保证服务器端渲染出正确的<a>标签结构，又能在客户端保留Next.js的路由跳转逻辑，彻底避免水合过程中的结构不匹配问题。

额外检查项 #

1. 确认NextLink从next/link正确导入，无路径错误
2. 确保NavBar组件中没有依赖客户端环境的条件渲染（比如typeof window !== 'undefined'），这类逻辑会导致服务器与客户端渲染结果差异
3. 检查urql的SSR配置是否正确，ssr: true会触发服务器端数据预取，需保证页面数据在服务器端已准备完成，避免因数据状态不一致引发UI差异

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