必须用document.documentElement.style.setProperty()批量更新CSS变量，因其作用域绑定在:root上，才能全局生效；禁用cssText全量覆盖，避免清空transform等已有内联样式。
直接用 document.documentElement.style.setProperty() 批量更新 CSS 变量是安全且高效的，但必须避免逐个调用、重复触发重绘，更不能用 cssText 覆盖整个 style 字符串——那会清掉所有其他内联样式。
为什么不能用 element.style.cssText = '...' 更新变量
因为 cssText 是一个“全量覆写”接口：只要赋值，就会把元素当前全部内联样式（包括非变量部分，比如 transform、z-index 等）一并抹掉。主题切换时若页面已有动态设置的内联样式（如动画位移、临时高亮），就会意外丢失。
- 错误示例：
document.documentElement.style.cssText = '--bg-color: #1a1a1a; --text-color: #fff;'; - 后果：之前通过
element.style.transform = 'scale(1.05)'设置的缩放立即失效 - 替代做法：只更新变量本身，不动其他属性
批量更新变量的正确写法：一次 setProperty + 循环
浏览器对 style.setProperty() 的调用做了优化，连续多次调用不会立刻触发重绘；真正渲染发生在 JS 执行完、进入下一帧时。所以放心循环，但别在循环里穿插读取操作（如 getComputedStyle）。
- 推荐写法：遍历对象键值对，统一调用
setProperty - 注意变量名必须带两个短横线前缀，如
'--primary-color'，不能漏掉 - 值要转成字符串，即使数字也要加引号，例如
'24px'，不能传24 - 示例：
const theme = { '--bg-color': '#1a1a1a', '--text-color': '#e6e6e6', '--border-radius': '8px' }; Object.entries(theme).forEach(([prop, value]) => { document.documentElement.style.setProperty(prop, value); });
如何避免变量更新后样式不生效
CSS 变量生效依赖于作用域和级联优先级。常见失效不是 JS 没执行，而是变量没被正确继承或被更高优先级规则覆盖。
立即学习“前端免费学习笔记（深入）”；
- 确保变量定义在
:root或目标元素上，不要只写在某个 class 里又忘了在 DOM 中挂载该 class - 检查是否误用了
document.body.style.setProperty()—— body 不是根作用域，变量不会全局生效 - 如果用了 Shadow DOM，需在对应 shadowRoot 的
host上设置，document.documentElement够不到 - 调试技巧：打开 DevTools → Elements → 选中
<html>→ 右侧 Styles 面板搜索--，确认变量已出现在element.style下
性能敏感场景下要不要用 requestAnimationFrame
一般不需要。单纯设置变量不触发 layout，也不强制重排，setProperty 是纯样式层更新，开销极低。只有当你在同一次 JS 执行中「先改变量、再读 offsetHeight」这类读写混合操作时，才可能因浏览器强制同步计算而卡顿。
- 安全做法：所有写操作（
setProperty）集中放在前面，所有读操作（getComputedStyle、offsetTop）统一放后面 - 真要压帧率：把变量更新包进
requestAnimationFrame只是为了对齐渲染时机，不是为“提速” - 更关键的是：别在滚动/输入事件里高频调用主题更新，加防抖或节流
真正容易被忽略的点是变量作用域和继承链——设了变量不代表样式自动应用，得看 CSS 规则里有没有用 var(--bg-color) 显式引用它，且该规则是否匹配到目标元素。变量本身只是“值容器”，不带样式逻辑。
