直接用document.documentElement.dataset.theme切换并配合:root[data-theme="xxx"]覆盖变量即可无刷新生效，因CSS变量实时求值且作用域限于:root；需确保变量全在:root声明、每个var()带回退值、选择器权重足够（如html[data-theme="dark"] :root）、初始化脚本置于防FOUC。
直接用 document.documentElement.dataset.theme 切换 + :root[data-theme="xxx"] 覆盖变量，就能无刷新切换主题——前提是变量必须全部定义在 :root 里，且每个 var() 都带回退值，否则页面会闪白或文字消失。
为什么只改 dataset.theme 就能无刷新生效
CSS 变量是实时求值的，[data-theme="dark"] :root 这类选择器一旦匹配，浏览器会在样式计算阶段重新读取所有 var(--x)，无需 JS 强制重绘。但这个机制只对挂载在 :root 上的变量起作用；写在 .theme-dark 类里或组件选择器中，变量根本不会被全局读到。
-
document.documentElement.dataset.theme = 'dark'必须操作document.documentElement，不是document.body或随便一个元素 - 对应 CSS 规则必须写成
html[data-theme="dark"] :root { --bg-color: #121212; }，不能漏掉:root - 如果用了
@layer base（比如 Tailwind 场景），变量声明得放在@layer base块内，否则可能被默认样式压住
var() 不生效的三个高频原因
最常见不是 JS 没执行，而是 CSS 层面断链：
- 变量没在
:root中声明：浏览器遇到未定义的var(--text-primary)直接 fallback 到transparent或继承值，不是“不变”，是“失效” -
var()缺少回退值：color: var(--text-primary)→ 文字变透明；正确写法是color: var(--text-primary, #333) - CSS 选择器权重不够：
.dark :root权重只有 10，容易被业务 class（如.card:hover）覆盖；改用html[data-theme="dark"] :root（权重 110）更稳
初始化阶段最容易踩的坑
首屏闪动（FOUC）几乎都出在这里：
立即学习“前端免费学习笔记（深入）”；
-
<script></script>必须塞进里，预设初始状态：document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light'; - 不能等
DOMContentLoaded再设 —— 此时浏览器已开始渲染，变量还没就位，就会先按默认色块画一遍，再闪一下切过去 - SSR 场景下，HTML 模板里就得硬编码
，否则服务端吐出的 HTML 没主题，客户端 JS 注入前就是白屏或错色
transition 写在哪才真正生效
transition: --bg-color 0.3s 完全无效，浏览器连警告都不抛。CSS 变量本身不可过渡，只能对它所应用的属性加 transition：
- ✅ 正确：
background-color: var(--bg-color); transition: background-color 0.3s ease; - ✅ 支持过渡的属性仅限 color、background-color、opacity、transform、box-shadow 等原生可插值属性
- ❌ 错误：对
border-radius: var(--radius-sm)加transition: border-radius可以，但若变量本身未定义，var()fallback 后值突变，过渡也会中断
真正难的从来不是“怎么切”，而是“第一次渲染就对”。变量声明位置、回退值、初始化时机、选择器权重——四个点只要漏一个，用户看到的就是闪屏、失色或按钮突然变透明。这些细节不显眼，但决定主题系统能不能上线。
