必须用document.documentElement.style.setProperty修改CSS变量，因其等价于:root，是唯一全局生效入口；需确保变量已在CSS中用:root声明，且传入值带单位、带--前缀，漏掉任一条件都会静默失败。
如何用 document.documentElement.style.setProperty() 修改 CSS 变量
直接改根元素的 style 是最常用也最稳妥的方式。CSS 变量作用域基于 DOM 树，:root 声明的变量会被所有后代继承，所以改 document.documentElement（即 <html>）就能全局生效。
注意别误写成 document.body —— 虽然也能生效，但若某些组件样式依赖 :root 作用域（比如用 var(--color-primary) 且未在局部重定义），只改 body 就会失效。
- 写法必须带双横线前缀：
setProperty('--color-primary', '#3b82f6')，漏掉--会静默失败 - 值要合法：颜色写
#3b82f6、rgb(59, 130, 246)或hsl(216, 71%, 59%)都行，但写'blue'这种关键字可能因浏览器解析差异导致不一致 - 避免重复调用：频繁 setProperty 会触发重排，批量修改建议先缓存，再一次性写入
为什么 getComputedStyle(document.documentElement).getPropertyValue() 有时返回空字符串
这不是 bug，而是 CSS 变量未被实际计算的结果。只有当变量在某个元素上被 var() 引用并参与样式计算后，getPropertyValue() 才能读到最终值；否则它只返回原始声明值（或空）。
真正需要“读取当前生效值”时，应该查具体元素的 computed style，而不是根元素：
立即学习“Java免费学习笔记（深入）”；
const el = document.querySelector('.button');
const color = getComputedStyle(el).color; // ✅ 返回 rgb(59, 130, 246)
如果非得从变量反推，稳妥做法是维护一个 JS 状态对象同步记录主题色，而非依赖 CSS 变量读取。
你接手一个需求时，是不是经常这样："改一个小字段 → 结果把不相关的代码也改了"、"需求说得很模糊 → 做着做着发现跑偏了"、"数据库加个字段 → 上线才发现漏了数据兼容"、"做了个新功能 → 一个月后自己都忘了当时怎么设计的"、"写到一半被中断 → 再回来不知道从哪继续"；这个 Skill 就是专门解决这些问题的。 它会自动探测你的项目环境（JDK、Spring Boot、ORM、数据库、前端框架），记在
-
getPropertyValue('--color-primary')返回空 ≠ 变量没设，只是没被引用计算过 - 动态改完变量后，立刻读取同一句里的
getPropertyValue很可能还是旧值，需等下一帧或强制 layout（不推荐） - 调试时可用浏览器开发者工具 Elements → Styles 面板，展开 :root 查看 “Computed” 里是否已更新
切换主题时要不要清空旧变量再设新值
不需要清空。CSS 变量覆盖是即时的，新 setProperty() 会直接替换旧值，不存在“残留”问题。强行 removeProperty('--color-primary') 反而可能导致回退到 fallback 值或继承值，引发意外色差。
真正要注意的是 fallback 逻辑是否健壮。例如：
:root { --color-primary: #3b82f6; }
.btn { background-color: var(--color-primary, #6366f1); }
如果 JS 误设了无效值如 setProperty('--color-primary', 'invalid') ，fallback #6366f1 就会生效 —— 这不是错误，而是 CSS 规范行为。
- 验证输入：设值前用
isValidColor(str)粗筛（比如正则匹配十六进制或 rgb/hsl 格式） - 避免设空字符串：
setProperty('--color-primary', '')会导致var(--color-primary, red)中的red生效 - 深色模式切换时，别只改颜色变量，记得同步更新
--color-bg、--color-text等语义变量，否则对比度可能不达标
用 CSSStyleSheet.insertRule() 动态注入变量安全吗
不推荐。虽然技术上可行，但存在明显缺陷：每次插入都会新增一条规则，无法干净覆盖；且 insertRule 对跨域样式表（如 CDN 加载的 CSS）会抛 SecurityError；更麻烦的是，它无法响应后续 JS 的变量修改 —— 你用 setProperty 改了变量，但 insertRule 写死的值还在那儿占着位置。
唯一适合它的场景是初始化时一次性注入整套主题变量（比如从 JSON 配置生成），之后全部交给 setProperty 管理。
- 优先走
document.documentElement.style，简单、可控、无兼容性问题（IE 不支持 CSS 变量，但现代项目基本不考虑） - 如果主题配置来自 API，拿到数据后统一用
Object.entries(theme).forEach(([key, val]) => rootStyle.setProperty(key, val))即可 - 避免混合使用：同一变量既用
insertRule又用setProperty，容易产生优先级混乱
主题色切换看着简单，但变量作用域、计算时机、fallback 行为这三点最容易出错。尤其在组件库嵌套深、多主题共存的项目里，靠肉眼调试很难定位是 JS 没设对，还是 CSS 里漏写了 var() 引用，或是 computed style 读错了地方。
