SSR后CSS变量闪烁的根本原因是服务端与客户端变量值不一致，导致样式错配和重绘跳变；必须在服务端HTML的中内联完整的:root变量声明，且next-themes需显式配置attribute="data-theme"以确保匹配。
服务端渲染（SSR）后 CSS 变量闪烁，根本不是变量本身的问题，而是变量值在服务端和客户端不一致，导致 class 名或样式规则错配——浏览器把服务端生成的 --color-primary 当成另一个变量，直接丢弃，首屏只能靠 fallback 或透明色硬扛。
为什么 SSR 后 document.documentElement.style.setProperty 会触发闪
这不是 JS 执行慢，而是服务端压根没设过这些变量。Node.js 环境里没有 document，setProperty 根本不会运行；等客户端 JS 加载完才设置，此时 HTML 已经按无变量状态渲染了一次。
- 服务端吐出的 HTML 中，
:root没有内联任何--*声明，浏览器全按默认值（比如var(--bg, #fff)里的#fff）走 - 客户端 JS 注入变量后，所有
var(--bg)才开始生效，但布局、字体、间距等已计算完毕，重绘必然跳变 - 若用
next-themes却没配attribute="data-theme"，它默认操作class，而你的 CSS 写的是[data-theme="dark"]，完全不匹配
必须在 HTML 字符串里内联 :root 变量声明
不能依赖 JS 注入，也不能靠外链 CSS。变量声明必须出现在服务端输出的 HTML 的 里，且要在任何引用它的样式之前。
- Next.js Pages Router：在
_document.tsx的getInitialProps中读取req?.headers['sec-ch-ua-mobile']或传入的 theme prop，拼成<style>:root { --bg: #121212; --text: #e0e0e0; }</style> - Next.js App Router：无法在服务端读系统偏好，必须 fallback 到 localStorage + 客户端同步；但首次 HTML 仍需占位，可用
<style media="print">:root { --bg: #fff; }</style>避免白屏，JS 加载后移除media并重写 - 变量值必须完整、成对：亮色和暗色变量都得声明，哪怕只是 fallback 值；漏一个
--border，对应组件就可能透明或错色
next-themes 配错 attribute 导致样式不生效
这个库默认用 class="dark"，但多数现代主题方案（包括 Tailwind darkMode: 'class' 和自定义 [data-theme]）要求的是 data-theme="dark"。不显式指定，就等于关掉了整个主题链。
立即学习“前端免费学习笔记（深入）”；
- 必须在
ThemesProvider上加attribute="data-theme"：<themesprovider attribute="data-theme">...</themesprovider> - CSS 规则必须严格对应：
[data-theme="dark"] { --bg: #121212; }，不能写成.dark { --bg: ... } - 服务端渲染时，
ThemesProvider的defaultTheme和storageKey必须与客户端 localStorage 实际存的 key 一致，否则 hydration 时读不到值，强制 fallback 到 light
最容易被忽略的是变量声明的“位置”和“完整性”：它必须是服务端 HTML 字符串的一部分，且每个用到的变量都得有初始值——少一个，就有一个地方闪；晚一步，就有一帧白。不是 JS 跑得不够快，是 HTML 从一开始就没给浏览器正确的输入。
