React 18 搭配 Chakra UI 时Head标签引发Hydration错误求助

针对你遇到的Hydration不匹配错误，以下是几个可行的解决方向，逐步排查即可解决问题：

1. 修复ChakraProvider的配置与颜色模式同步 #

Hydration错误常因服务器与客户端的颜色模式渲染不一致导致，需确保颜色模式初始化逻辑正确，同时规范组件嵌套结构：

修改_app.tsx，添加ColorModeScript并确保根容器为单个div：

import * as React from "react"
import { ApolloProvider } from "@apollo/client"
import { ChakraProvider, ColorModeScript } from "@chakra-ui/react"
import Head from "next/head"
import { useApollo } from "lib/apollo/client"
import { theme } from "lib/theme"

export default function App(props: any) {
  const { Component, pageProps } = props
  const apolloClient = useApollo(pageProps.initialApolloState)
  const getLayout = Component.getLayout ?? ((page: any) => page)

  return (
    <div>
      <Head>
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      </Head>
      {/* 同步服务器与客户端的初始颜色模式 */}
      <ColorModeScript initialColorMode={theme.config.initialColorMode} />
      <ChakraProvider theme={theme}>
        <ApolloProvider client={apolloClient}>
          {getLayout(<Component {...pageProps} />)}
        </ApolloProvider>
      </ChakraProvider>
    </div>
  )
}

2. 排查组件中的浏览器环境依赖 #

任何在服务器渲染阶段访问window、document等浏览器对象的代码，都会导致Hydration不匹配。需将这类逻辑移至客户端生命周期：

• 将依赖浏览器的代码放入useEffect：

import { useEffect, useState } from "react"

function ResponsiveComponent() {
  const [screenWidth, setScreenWidth] = useState(0)

  useEffect(() => {
    // 仅在客户端执行
    setScreenWidth(window.innerWidth)
  }, [])

  return <div>当前宽度：{screenWidth}</div>
}

• 对完全依赖浏览器的组件，使用Next.js的动态导入禁用SSR：

import dynamic from "next/dynamic"

// 该组件仅在客户端渲染
const ClientOnlyChart = dynamic(() => import("../components/Chart"), {
  ssr: false,
})

3. 确保布局函数无渲染不一致逻辑 #

检查Component.getLayout方法，确认其中没有服务器与客户端行为不同的代码（比如条件渲染依赖客户端状态），若有则调整为两端一致的逻辑，或移至客户端执行。

4. 用Suspense包裹异步内容 #

若页面或组件中包含Apollo查询等异步数据获取逻辑，需用Suspense包裹，避免Hydration阶段因数据未就绪导致的渲染差异：

import { Suspense } from "react"
import { useQuery } from "@apollo/client"
import { GET_DATA } from "../queries"

function DataPage() {
  const { data } = useQuery(GET_DATA)

  return (
    <Suspense fallback={<div>加载中...</div>}>
      <div>{data?.content}</div>
    </Suspense>
  )
}

通过以上步骤调整后，Hydration错误应该能被解决，Chakra UI即可在Next.js（React 18）中正常使用。

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