主题切换失效的根源是CSS变量变更未触发重绘，须通过class切换作用域、设置fallback容错、准确操作document.documentElement三者协同解决。
直接改 :root 里的变量值，页面不会自动重绘——这是主题切换失效最常被忽略的底层原因。
为什么只调用 style.setProperty() 不够
浏览器不会因为 --bg-color 值变了，就重新计算所有 background-color: var(--bg-color) 的元素。它只在样式计算阶段读一次变量，之后除非触发重排或属性值“显式变化”，否则不更新。
- 常见现象：JS 执行了
document.documentElement.style.setProperty('--bg-color', '#1a1a1a')，但按钮、卡片背景色没变 - 根本问题：CSS 变量是实时求值的，但依赖它的属性（如
color）本身没“动”，浏览器不认为需要重绘 - 最稳妥解法不是硬刷变量，而是靠 class 切换来触发整套样式重解析
:root 和 .theme-dark :root 的优先级怎么写才生效
必须让深色主题的变量定义能覆盖默认 :root，光靠顺序不够，得靠选择器权重。
- 错误写法：
.theme-dark { --bg-color: #1a1a1a; }—— 这是在.theme-dark元素上设变量，但:root是html，它不匹配 - 正确写法：
html.theme-dark :root { --bg-color: #1a1a1a; }或更简洁的.theme-dark :root { --bg-color: #1a1a1a; }（前提是 class 加在html上） - 注意：不能写成
body.theme-dark :root，:root永远只匹配根元素，和body无关 - 如果用了
data-theme="dark"，对应写html[data-theme="dark"] :root
JS 切换时该操作 document.documentElement 还是 document.body
必须操作 document.documentElement，其他方式都不可靠。
立即学习“前端免费学习笔记（深入）”；
- 加 class：
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.querySelector('html').style.setProperty(...)—— ❌ 不推荐，document.documentElement是标准且唯一可靠的引用
fallback 回退值不是“备用”，是防崩底线
var(--text-color, #333) 的第二个参数，在变量未定义、拼错、或 JS 设置失败时立刻兜底，防止整个 UI 文字消失或变透明。
- 别写
var(--text-color, var(--fallback-color))—— 嵌套var()在旧版 Safari 中可能解析失败 - 别省略 fallback：
color: var(--text-color)等于color: inherit，不是你想的黑色 - 空格敏感：写成
var(--c, #000 )（末尾空格）在 Safari 13.1 之前会报解析错误 - 单位要一致：如果变量本意是尺寸，fallback 写
16px没问题，但写1rem可能在某些 Android WebView 中失效
真正难的不是定义变量，而是让变量变更这件事“被浏览器看见”——class 控制作用域 + fallback 容错 + document.documentElement 准确操作，三者缺一不可。稍有偏差，就会出现“代码写了，控制台没报错，但页面就是不换色”的情况。
