闪屏主因是css变量未就绪即渲染首帧，解法唯二：内联默认变量+同步初始化。需在内联:root变量兜底，js初始化脚本置于css前同步执行，确保样式计算前data-theme已设置。
闪屏不是 JS 慢，是 CSS 变量还没就绪浏览器就渲染了第一帧。核心解法只有两个：内联默认变量 + 同步初始化，缺一不可。
为什么切换 data-theme 会闪屏
根本原因不是 JS 执行慢，而是浏览器渲染时机早于 CSS 文件解析完成。比如你执行 document.documentElement.setAttribute('data-theme', 'blue') 时，如果 [data-theme="blue"] 对应的 CSS 还没加载或解析完，浏览器会先按 :root 里旧的 --color-bg 渲染一帧，再重绘——肉眼可见“白→蓝”跳变。
加 transition 或 opacity 动画掩盖不了问题，因为变量值本身是空或 fallback 到初始值，动画只是在错的值之间过渡。
- 变量未就绪前，
bg-[var(--color-bg)]实际取的是unset或继承值，不是你想的“淡入” - 哪怕用了
localStorage记住主题，如果 JS 初始化晚于首帧渲染，照样闪 -
DOMContentLoaded太晚；useEffect/onMounted更晚；必须抢在样式计算前
必须在
在 HTML 的 里塞一段内联 <style></style>，定义最小集变量，让浏览器首帧就有可用值：
<style>
:root {
--color-bg: #fff;
--color-text: #1f2937;
--color-primary: #3b82f6;
}
</style>
这些值不一定要和任一主题完全一致，但必须是合法、非透明、非继承的兜底值。重点是避免 background-color: var(--color-bg) 在首次计算时 fallback 成 transparent 或 initial。
- 别只写
--color-bg，漏掉--border-color或--shadow-sm，那些用到的地方会突然变透明或无边框 - 所有主题块（如
[data-theme="dark"]）都必须完整覆盖同一组变量名，命名不一致就会分裂 - 变量名统一收口，例如全用
--color-*前缀，禁用--primary、--theme-primary混用
JS 初始化必须同步且尽早执行
把初始化逻辑写成内联脚本，放在 里、CSS <link> 之前，确保它在任何样式计算前运行：
<script>
const saved = localStorage.getItem('theme') || 'light';
document.documentElement.setAttribute('data-theme', saved);
</script>
不要封装函数，不要等事件，不要进框架生命周期钩子——就是一行赋值，越早越好。
- 设在
上，不能设在或组件节点，否则继承链断裂 - 每次切换后必须立刻同步
localStorage.setItem('theme', 'dark')，否则刷新即失效 - 如果用 Vue/React，别在组件里改
data-theme，应在入口或根布局中统一控制
tailwind.config.js 必须配对 safelist 和 @layer base
Tailwind 默认会忽略 bg-[var(--color-bg)] 这类任意值，构建时直接删掉，导致样式丢失。必须显式放行：
safelist: [ 'bg-[var(--color-bg)]', 'text-[var(--color-text)]', 'border-[var(--border-color)]', ],
同时，所有变量声明必须写在 @layer base 块里，并挂载到 :root：
@layer base {
:root {
--color-bg: #fff;
}
[data-theme="dark"] {
--color-bg: #111827;
}
}
-
var(--color-bg)中括号必须英文半角，不能有空格：var( --color-bg )会编译失败 - 别混用
dark:和data-theme，dark:bg-gray-900在data-theme="dark"下完全不生效 - 第三方 UI 库（如 Headless UI）默认只认
dark:，需 patch 其 class 生成逻辑才能响应data-theme
最易被忽略的其实是变量命名一致性与初始化顺序：一个项目里 --primary、--color-primary、--theme-primary 并存，会导致部分组件用 A 变量、部分用 B 变量，切换时颜色分裂。统一收口比写十个切换函数更重要。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
