水合失败源于服务端与客户端 classname 不一致，导致 react 跳过复用并强制重绘；serverstylesheet 必须每次请求新建实例，collectstyles 需包裹顶层 app 树，getstyletags 返回的 style 标签须插入 head，且两端 styled-components 版本、环境变量及样式生成逻辑必须完全一致。
水合失败不是样式没加载完，而是服务端生成的 className 和客户端首次 render 生成的不一致——React 直接跳过复用，强制重绘，FOUC 立刻出现。
ServerStyleSheet 必须每次请求新建实例
Node.js 进程长驻，若在模块顶层写 const sheet = new ServerStyleSheet()，这个实例会被多个请求共享。一旦 collectStyles() 被调用并消费，后续请求再调用就会报错：Can't collect styles once you've consumed a ServerStyleSheet's styles!，且样式完全不输出。
- ✅ 正确：在 Express 的
res.render回调、Next.js Pages Router 的getInitialProps或自定义 SSR 函数内，每次渲染前调用new ServerStyleSheet() - ❌ 错误：在文件顶部声明后到处 import，或在中间件外初始化
- ⚠️ Next.js App Router 下
ServerStyleSheet基本不可用——它不兼容 React Server Components 的流式渲染模型
collectStyles 必须包裹整个 App 树，且 getStyleTags() 插入
collectStyles 是收集器，不是装饰器。只有被它包裹的组件树中实际渲染的 styled 组件，其样式才会被捕获。漏掉任意一层（比如只包了 <header></header>），对应样式就永远不会出现在服务端 HTML 中。
- ✅
sheet.collectStyles(<app></app>)必须作用于顶层入口组件 - ✅
sheet.getStyleTags()返回的是字符串，必须作为<style></style>标签插入最终 HTML 的内，不能丢弃、不能插到底部 - ⚠️ Next.js Pages Router 需通过
props.styles透传，并在_document.tsx的中渲染；App Router 则需放弃该方案，改用@emotion/server或静态提取
服务端与客户端 class 名必须字面级一致
哪怕一个字符不同（如哈希值差一位），React 就判定 DOM 不匹配，跳过 hydration，样式全部重算。
- ✅ 确保两端使用**完全相同版本**的
styled-components（检查package-lock.json，避免 v5/v6 混用） - ✅ 生产环境必须设
process.env.NODE_ENV = 'production'，否则服务端不 hash class 名，客户端却按 hash 规则找，必然失败 - ✅ 所有影响样式的值必须可复现：禁用
Date.now()、Math.random()、useContext、props中非确定性计算——这些在服务端无法稳定执行
真正难排查的是那些「看起来正常」的场景：比如构建时 PostCSS 插件配置不一致、css-loader 的 localIdentName salt 不同、甚至 CI/CD 中 Node 版本差异导致 hash 算法微变——这些都会让 class 名在两端悄悄错开。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
