唯一避免首屏主题闪烁的做法是在服务端或HTML解析早期注入data-theme属性；客户端JS设置必然导致FOUC，因样式已计算并渲染完毕，后续修改仅触发重绘甚至重排，尤其影响布局属性和Safari渐变等场景。
直接在服务端或 HTML 解析早期注入 data-theme 属性，是唯一能避免首屏主题闪烁（FOUC）的做法。靠客户端 JS 在 useEffect 或 DOMContentLoaded 里读 localStorage 再设属性，必然闪。
为什么 document.documentElement.style.setProperty() 会闪
因为这行代码执行时，HTML 已渲染、CSS 已计算完毕、页面已画出第一帧——此时改变量，浏览器只能触发重绘（甚至重排），而无法回溯修正初始样式。尤其当变量用于 margin、font-size 或 background-image 时，尺寸或图层会突变，视觉跳动更明显。
- 变量若绑定到布局属性（如
--gap→gap: var(--gap)），每次变更都会强制同步布局计算 - 多个组件同时响应同一变量变化，可能堆积重绘任务，导致掉帧
- Safari 对
linear-gradient(var(--color))类写法更新滞后，常出现一帧空白 - 父级用了
contain: paint，子元素变量更新会触发合成层重建，造成白块闪
怎么让 data-theme 在 CSS 解析前就生效
核心是绕过 JS 水合时机，把主题判断逻辑“抢跑”到 <head> 的内联脚本中，确保浏览器解析 CSS 前，document.documentElement 上已有正确属性。
- 在
app/layout.tsx的<head>里插入立即执行函数：(function() { const theme = localStorage.getItem('theme'); if (theme) { document.documentElement.setAttribute('data-theme', theme); } })(); - 必须和
next-themes的themeStorageKey保持一致（默认是theme） -
tailwind.config.js中darkMode: 'class'必须启用，且content路径要包含app/layout.tsx，否则 Tailwind JIT 扫不到内联脚本里的data-theme="dark" - 不要用
link.onload或DOMContentLoaded触发设置——都太晚
哪些 CSS 变量用法不容易闪
安全的前提是：不改变盒模型、不依赖运行时计算、不触发强制重排。变量只是“值容器”，真正过渡的是它所服务的属性。
立即学习“前端免费学习笔记（深入）”；
- 只用于纯绘制属性：
color、background-color、border-color、opacity—— 这些可 GPU 合成，浏览器优化充分 - 配合预定义动画开关：
animation: var(--skeleton-enabled, none)，变量只控制是否启用已声明的@keyframes - 作为
@media或@supports的静态注入入口，比如@media (prefers-color-scheme: dark) { :root { --text: #eee; } } - 伪元素内容：
::before { content: var(--label); }，但需注意部分浏览器对变量更新有渲染延迟
最容易被忽略的是：即使用了 next-themes，如果没在 app/layout.tsx 顶层包裹 ThemesProvider，或者把它放在条件渲染分支里（比如 {isClient && <themesprovider>...</themesprovider>}），服务端就无法提前注入 data-theme —— 闪依然会发生。
