直接修改 :root 变量值不会触发重绘，主题切换必然失效；必须通过 class 切换（如 .theme-dark :root）触发样式树重建，或配合 getComputedStyle 强制刷新，同时 var() 必须设静态 fallback 防崩溃。
直接改 :root 里的变量值不会触发重绘，主题切换必然失效——这是最常被忽略的底层机制问题。
为什么 style.setProperty() 单独调用不生效
浏览器只在样式计算阶段读取一次 var() 的值，之后即使你用 document.documentElement.style.setProperty('--bg-color', '#1a1a1a') 改了变量，已渲染的元素也不会自动更新 background-color: var(--bg-color)。
- 常见现象：JS 执行成功，但按钮、卡片背景色完全没变
- 根本原因：
var()是实时求值，但依赖它的属性本身没“变化”，浏览器不认为需要重排重绘 - 单纯设内联变量只是改了值，没触发级联重解析，等同于“改了配方但没重新做菜”
.theme-dark :root 选择器写法必须精准
想让深色主题变量覆盖默认值，不能只靠声明顺序，必须靠选择器权重确保生效。
- 错误写法：
.theme-dark { --bg-color: #1a1a1a; }—— 这是在.theme-dark元素上设变量，而:root是html，根本不匹配 - 正确写法：
.theme-dark :root { --bg-color: #1a1a1a; }（前提是 class 加在html上） - 如果用
data-theme="dark"，对应写html[data-theme="dark"] :root - 千万别写成
body.theme-dark :root——:root永远只匹配根元素，和body无关
切换时必须操作 document.documentElement
所有操作必须落在 html 元素上，其他路径都不可靠。
立即学习“前端免费学习笔记（深入）”；
- ✅ 正确：
document.documentElement.classList.toggle('theme-dark') - ❌ 错误：
document.body.classList.toggle('theme-dark')—— class 加在body上，对:root定义无影响 - ✅ 可用但需配合：
document.documentElement.style.setProperty('--bg-color', '#1a1a1a')，但必须同步加 class 触发重解析，或手动调用getComputedStyle(document.documentElement)强制刷新 - ❌ 不推荐：
document.querySelector('html').style.setProperty()——document.documentElement是唯一标准且稳定的引用
var() 的 fallback 值不是可选项，是防崩底线
var(--text-color, #333) 的第二个参数，在变量未定义、拼错、或 JS 设置失败时立刻兜底，防止文字消失或 UI 崩溃。
- 别写
var(--text-color, var(--fallback-color))—— 旧版 Safari 对嵌套var()支持不稳定 - fallback 必须是静态值或简单表达式，不能依赖另一层变量求值
- 尤其在 SSR 场景下，首屏 HTML 若没预置
data-theme，变量可能短暂未定义，fallback 就是第一道防线
真正卡住人的从来不是怎么写 var()，而是忘了浏览器不会因为你改了一个变量就重画整页——它只认 class 切换带来的样式树重建。这个点漏掉，后面所有逻辑都会静默失败。
