You need to enable JavaScript to run this app. NextJS getServerSideProps下动态className不匹配报错排查
优惠活动
大模型
产品
解决方案
定价
更多

NextJS getServerSideProps下动态className不匹配报错排查

报错根本原因

这是Next.js 基于SSR渲染流程的水合阶段属性不匹配问题,和项目接入的Material UI、.babelrc里的styled-components配置没有直接关联。因为报错指向的className是你手动写的自定义字符串,不是CSS-in-JS生成的动态哈希类名,不存在服务端样式提取、序列化不匹配的问题。

对应报错信息的错配逻辑非常明确:

  • 服务端执行getServerSideProps、生成最终页面静态HTML时,渲染这个Header组件计算出的className是空字符串"",代表这个阶段拿到的darkMode值为false。
  • 客户端首次加载页面、执行组件水合逻辑时,第一次渲染Header组件计算出的className是"dark",代表这个阶段拿到的darkMode值为true。
    两边对同一个DOM元素的同一个属性计算结果不一致,React就会抛出这个匹配提示。
结合你贴的代码的具体触发场景
  • 最常见的触发原因是状态初始化逻辑存在服务端/客户端的执行环境差异:实现深色模式时,很多人会在给useState设置初始值时,混合读取浏览器独有的数据源(比如localStorage存储的用户主题偏好、window.matchMedia检测的系统主题),但这些API在服务端的Node执行环境里完全不存在。服务端因为读不到这些值,就会走默认false的分支,渲染出空的className;而客户端首次执行组件时,可以直接读取这些浏览器端的数据源,拿到true的计算结果,两边就出现了输出差异。
  • 你当前的组件写法本身存在容易踩坑的点:将props传入的darkMode直接作为useState的初始值语法上没有问题,但如果getServerSideProps返回的darkMode值,在服务端计算阶段和客户端注入的页面初始数据存在序列化差异,也会触发两边计算结果不一致。
  • 你观察到的“调试时看到darkMode实际为true,但div没渲染对应className”,是这类水合报错的典型表现:React检测到属性不匹配时,为了不破坏已经加载完成的服务端HTML,不会在水合阶段直接替换DOM上的原有属性,会优先保留服务端输出的空className;只有等整个水合流程走完、后续触发组件状态更新时,才会重新计算并更新DOM属性。所以你能在调试面板里看到内存中的状态值是true,但DOM节点上的className根本没有更新。

内容的提问来源于stack exchange,提问作者doorman

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.10 19:24:06