SSR中CSS-in-JS样式闪烁的根本原因是服务端与客户端在类名生成、样式注入、hydration时机三环节断开同步:类名哈希不一致导致DOM重绘,服务端未调用extractCritical致style标签缺失,hydrate早于CSS解析完成引发FOUC。

SSR 中 CSS-in-JS 出现样式闪烁(FOUC 或 layout shift),不是因为“CSS 没加载完”,而是服务端与客户端在三个关键环节断开同步:类名生成不一致、服务端未提取并注入样式、客户端 hydration 过早触发。
类名哈希不一致导致 DOM 重绘
CSS-in-JS 库(如 Emotion、Styled Components)在服务端和客户端必须用完全相同的哈希上下文生成 class 名。一旦 mismatch,React hydration 会直接丢弃服务端 HTML,强制重渲染——这不是警告,是不可逆的 DOM 替换。
-
createCache({ key: 'ssr' })的key必须两端完全一致;漏写、拼错、或混用 v11/v12 版本都会导致哈希算法不同 - CSS Modules 场景下,Vite 或 Webpack 必须显式配置
css.modules.generateScopedName,不能依赖默认值;若启用lightningcss,还需设scopeBehaviour: 'local' - 禁用
css.modules.symbols:它在 SSR 中引入非确定性模块 ID,极易引发 cache 错配
服务端没调用 extractCritical 导致 style 标签缺失
CSS-in-JS 的规则默认只存在内存 cache 中,不会自动变成字符串塞进 HTML。服务端若跳过样式提取,等于“白渲”——HTML 的 里压根没有对应 <style></style>。
Lightning CSS 是由 Parcel 团队开发的基于 Rust 的 CSS 解析器、转换器、打包工具和压缩工具。此技能适用于需要优化样式表、为目标浏览器降低现代 CSS 语法以及将快速 CSS 处理集成到构建或重构工作流中的代理。
- Emotion v11 必须调用
extractCritical(html);v12+ 改为renderStylesToString(cache),且每次请求都得新建cache实例(不能模块顶层复用) -
CacheProvider必须包裹整个<app></app>树,漏掉任意一层(尤其是含@keyframes的组件),该部分样式就收不到 - 最终返回的 HTML 中,
必须包含提取出的 CSS 字符串,且需验证其中是否存在类似@keyframes css-xyz { }的动画规则——缺失即说明收集不全
hydrate 执行时机早于 CSS 解析完成
即使类名一致、<style></style> 已内联,如果 hydrateRoot 在浏览器还没解析完内联样式时就执行,仍会先按无样式渲染一次,再重绘,造成肉眼可见的闪。
立即学习“前端免费学习笔记(深入)”;
- 不要在
DOMContentLoaded回调里触发 hydrate;应监听<link rel="stylesheet">的onload,或对内联<style></style>使用media="print" onload="this.media='all'"确保解析就绪 - 若使用外部 CSS 文件(如
ssr-styles.css),必须以同步<link>方式加载,禁用preload + onload切换——异步切换必然 FOUC - 检查
@media (prefers-color-scheme)等响应式规则是否被完整提取,缺失会导致暗色模式下首屏错乱
最易被忽略的是:类名 mismatch 和 hydration 时机问题往往同时存在,但开发者常只修复其一。比如改对了 key 却忘了等 onload,或等了 onload 却因 css.modules.symbols 导致哈希错配——两者任一失败,抖动就无法根除。

















