React hydration mismatch 根本原因是服务端与客户端 class 名生成逻辑不可复现，需确保 CSS-in-JS SSR 配置一致、禁用非确定性值、同步获取状态、统一构建配置及样式注入机制。
服务端渲染时 className 和客户端不一致导致 React hydration mismatch
这是同构渲染中最典型的 CSS 工具报错，React 会抛出类似 Warning: Prop `className` did not match. 的警告，本质是服务端生成的 HTML 中 class 名和客户端首次 render 生成的不一致。根本原因不是 CSS 工具本身有问题，而是 class 名生成逻辑在两端不可复现——比如用了随机 hash、依赖运行时时间戳、或没启用 SSR 安全模式。
- 确保 CSS-in-JS 库启用 SSR 支持：如
@emotion/react必须配CacheProvider+ 服务端createCache，且传入相同key；styled-components必须用ServerStyleSheetcollectStyles 并注入到 HTML；linaria需开启ssr: true且不使用运行时计算的样式 - 禁止在样式定义中引用组件 props、useContext、Date.now()、Math.random() 等客户端独有或非确定性值——这些在服务端无法复现，会导致 class 名每次都不一样
- 检查是否意外启用了开发模式：比如
emotion在process.env.NODE_ENV === 'development'下默认加前缀或改名，而服务端可能用 production 构建，造成 class 名差异
clsx 或 classnames 在 SSR 中动态拼接 class 出现空格/顺序不一致
这类工具本身无 SSR 问题，但容易在服务端和客户端因数据加载时机不同，导致条件判断结果不一致。例如服务端数据未就绪时 isActive 是 false，客户端取到数据后变成 true，class 列表就变了。
- 服务端必须同步获取所有影响 class 的状态：比如路由参数、用户登录态、API 数据——不能等
useEffect或fetch异步填充后再算 class - 避免用对象形式传入
clsx({ active: isActive })时依赖未定义变量，服务端若isActive是undefined，结果为false；客户端可能是null或0，被转成true，造成不匹配 - 推荐显式判断：用
clsx('btn', isActive && 'btn--active')而非clsx({ 'btn--active': isActive })，减少隐式类型转换带来的歧义
PostCSS 或构建插件导致服务端与客户端 class 名 hash 不一致
常见于用 css-loader + mini-css-extract-plugin 做 CSS 模块化，或 PostCSS 插件（如 postcss-modules）生成 scoped class。如果服务端构建和客户端构建配置不完全一致（比如一个开了 localIdentName 的 hash salt，另一个没开），两端生成的 class 名就会对不上。
- 服务端和客户端必须共用同一份 webpack / Vite / Rspack 配置，尤其是
css-loader的modules.localIdentName、modules.exportLocalsConvention和ident字段 - 禁用基于文件路径的 hash 变量（如
[path]），因为服务端和客户端的绝对路径可能不同；优先用[name]_[local]_[hash:base64:5]这类稳定字段 - 如果用
cssnano压缩，确保服务端和客户端都禁用reduceIdents和zindex等可能重写 class 名的规则
服务端提取的 style 标签没插入到正确位置，导致客户端 rehydration 时找不到对应 rule
React hydrate 时会比对 DOM 结构，如果服务端注入的 <style> 内容和客户端 runtime 注入的不一致（比如顺序错、内容少、被去重），也会触发 class 匹配失败。典型表现是服务端有 .abc123 { color: red }，客户端却生成了 .def456 { color: red }。
立即学习“前端免费学习笔记（深入）”；
- 服务端必须完整收集所有用到的样式并一次性注入到
<head>，不能漏掉按需加载的组件样式（比如异步路由组件里的import('./Button.css')） - 确保服务端和客户端使用同一套样式注入机制：比如都走
styled-components的ServerStyleSheet+StyleSheetManager，不要服务端用collectStyles，客户端又手动injectGlobal - 检查 HTML 模板中是否有多余的
<style data-emotion>标签残留——旧缓存或 CDN 返回的页面可能带过期 style，干扰 hydrate
最常被忽略的是「服务端数据获取」和「样式生成」的耦合点：只要有一个 class 名依赖的数据在服务端没拿到，整个链路就断了。不是工具不支持 SSR，而是它不会帮你补数据缺口。
