最稳的主题切换方案是预定义主题class+切换document.documentElement.classList+本地存取+系统偏好fallback；因CSS层叠优先级高于var()，直接setProperty无效，需确保变量未被更高权重规则覆盖且所有引用位于:root声明之后。
直接改 :root 变量值没反应，不是 JS 没执行，而是 CSS 层叠优先级压过了 var()；用 link 切换 CSS 文件闪屏、加载延迟；最稳的路径是：预定义主题 class + 切换 document.documentElement.classList + 本地存取 + 系统偏好 fallback。
为什么 setProperty('--color', 'red') 无效？
CSS 变量只传值，不改层叠顺序。哪怕你用 JS 成功设置了 document.documentElement.style.setProperty('--primary', '#ff6b6b')，只要页面里有更具体的选择器硬编码颜色（比如 .card-header { color: #222; }），它就会盖过 var(--primary) 的计算结果。
- 用浏览器开发者工具检查元素的 computed
color值，看它是否真来自var(--primary) - 确保所有用变量的地方都写在
:root声明之后，且没有同名属性被更高权重规则覆盖 - 避免在内联样式里写
style="color: blue"—— 它会直接屏蔽var()
用 class 切换主题比反复 setProperty 更可靠
频繁调用 setProperty 容易漏设、难追踪、触发重排；而预定义主题 class，靠 DOM class 切换驱动整套变量更新，逻辑清晰、性能可控。
-
:root只定义默认值，例如：--bg: #fff; --text: #333; - 每个主题单独写 class，如
.theme-dark，并在其中覆盖变量：.theme-dark { --bg: #121212; --text: #f0f0f0; } - JS 切换只需一行：
document.documentElement.classList.toggle('theme-dark') - 必须作用于
<html>或其祖先，后代才能继承这些变量值
刷新不丢主题：localStorage 读取时机很关键
等 DOMContentLoaded 再读 localStorage，页面会先按默认主题渲染，再跳变——这就是闪屏。必须在 HTML 解析阶段就注入 class。
立即学习“前端免费学习笔记（深入）”；
- 把脚本写在
<head>里，用document.documentElement.classList.add()立即生效 - 读取时优先用
localStorage.getItem('theme')，未命中则 fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches - 切换主题时同步写入：
localStorage.setItem('theme', 'dark') - 注意：
localStorage值是字符串，判断时别漏掉=== 'dark'这类严格比较
data-theme 和 class 切换的区别在哪？
两者都能工作，但语义和兼容性不同。data-theme="dark" 是自定义属性，需配合 [data-theme="dark"] 选择器；而 class="theme-dark" 是原生 class，支持更多工具链（比如 Tailwind 的 class 推导、CSS-in-JS 的主题插件）。
-
data-theme更语义化，适合强调“主题状态”而非“样式归属” -
class更轻量、更通用，浏览器解析更快，且能被大多数构建工具识别 - 如果你用框架（如 React），
className控制 class 比操作dataset更自然 - 别混用：不要同时用
data-theme和class控制同一套变量，容易冲突
真正麻烦的不是切换动作本身，而是变量被覆盖的位置、本地存储读取的时机、以及系统偏好 fallback 的判断边界——这些点不卡准，用户一眼就能看出“主题切换不稳”。
