必须用 :root 定义变量并用 document.documentElement.style.setProperty() 修改，颜色需拆为 RGB/HSL 分量；变量作用域限于继承链，:root 是唯一全局有效位置，同名变量就近覆盖，setProperty() 易因前缀缺失、类型错误或作用域错位失效。
直接结论：必须用 :root 定义变量，用 document.documentElement.style.setProperty() 修改，且颜色值不能直接存十六进制或关键词——得拆成 RGB 或 HSL 分量再组合。
为什么 var(--color) 写在元素上却没变色？
根本原因不是 JS 没执行，而是变量作用域断了。CSS 变量只继承自祖先，不跨选择器生效。
-
:root是唯一能保证全局可读的位置；写在.card或body里，子元素可能读不到 - 如果某个组件自己定义了同名变量（比如
.theme-dark { --text-color: #fff; }），它会覆盖:root的值——就近原则优先 - 检查 computed styles 里 color 的最终值是不是你设的 RGB 字符串，而不是
var(--text-color)这个字面量
setProperty() 改颜色值总失效的几个硬伤
静默失败最常见，浏览器不会报错，但颜色纹丝不动。
- 漏掉双短横线前缀：
document.documentElement.style.setProperty('primary-color', '#3b82f6')❌，必须是'--primary-color'✅ - 传数字不带引号：
el.style.setProperty('--alpha', 0.3)在部分 Safari 上异常；写成'0.3'更稳 - 改了
document.body.style却指望全局响应——body不等价于:root，某些伪类或根级样式可能根本没继承到 - 变量虽已修改，但目标元素被内联
style="color: red"覆盖，var()级联失败
RGB 和 HSL 哪种更适合动态改色？
取决于你要改什么。RGB 更直觉、更可控；HSL 更适合换主色调但保协调。
立即学习“前端免费学习笔记（深入）”；
- 想微调亮度或单个通道（比如只让蓝色更深）：用
--main-r/--main-g/--main-b，然后color: rgb(var(--main-r), var(--main-g), var(--main-b)) - 想一键切换主题色系（蓝→紫→绿）：用
--hue，配合固定--saturation和--lightness，写成color: hsl(var(--hue), var(--saturation), var(--lightness)) - RGBA 透明度必须单独定义
--alpha，且值是0–1小数，'30%'或30都无效 - HSL 的
hsl()函数对变量支持略弱于rgb()，动画中偶有闪烁，生产环境建议先实测
localStorage 同步主题时容易忽略的细节
存取逻辑本身简单，但状态一致性常被轻视。
- 页面加载时，先读
localStorage，再用setProperty()设置变量，**必须确保 DOM 已挂载**，否则操作无效 - 别在
:root里写 fallback 值如var(--primary-color, #007bff)，因为 localStorage 读取是异步的，fallback 会先生效，造成闪屏 - 深色模式检测要手动覆盖
prefers-color-scheme：设置data-theme="dark"并在 CSS 中用[data-theme="dark"] { --bg: #111; }覆盖，否则系统偏好会干扰 - 修改后立刻读
getComputedStyle(document.documentElement).getPropertyValue('--primary-color')得到的可能是旧值——它返回声明值，不是计算后结果；真要验证，查具体元素的computedStyle.color
真正卡住人的从来不是语法，而是变量是否被引用、是否被覆盖、是否在正确作用域里被继承——打开 DevTools 的 Elements → Styles 面板，盯着 :root 下的 “Computed” 栏，比写十行 JS 更快定位问题。
