直接操作 document.documentElement.style 是最简路径批量更新 CSS 变量，用 setProperty() 增量更新、避免 cssText 覆盖，注意作用域屏蔽与 FOUC 防范。
直接操作 document.documentElement.style 是最简路径
批量更新多个 CSS 变量，本质是往根元素的 style 属性里写多条 --key: value。绕开 :root 伪类或外部样式表，直接改 document.documentElement.style 最快、最可控，且无需重新计算样式作用域。
常见错误是试图用 document.querySelector(':root').style —— 这会返回空对象，因为 :root 不是真实 DOM 节点；也有人误用 getComputedStyle(document.documentElement)，但它只读，不能赋值。
实操建议：
- 用
Object.entries()遍历变量对象，避免手动拼接字符串 - 对值做基础类型检查：数字自动补单位（如
px），但0、100%、transparent等需保留原格式，别一刀切加单位 - 避免在循环中反复读写
style.cssText，性能差；优先用setProperty()
setProperty() 比 cssText 更安全可靠
用 element.style.cssText = '...' 会覆盖已有内联样式，哪怕只是想改一两个变量；而 setProperty() 是增量更新，不碰其他声明。
立即学习“Java免费学习笔记（深入）”；
示例场景：你只想更新 --primary 和 --spacing-md，但根节点已有 --font-size-base 内联定义——用 cssText 会清掉它，setProperty() 不会。
实操建议：
- 统一用
document.documentElement.style.setProperty('--key', value) - 值为
null或undefined时，setProperty()不会清除变量，要用removeProperty('--key') - 如果变量值含 CSS 函数（如
var(--color)、rgb(255, 0, 0)），确保字符串原样传入，不要额外转义
注意 CSS 变量作用域与继承链影响
根节点定义的变量默认全局可用，但若子元素显式设置了同名变量（比如 div { --primary: blue; }），那它和后代就看不到根节点的值了——这不是“覆盖”，而是作用域屏蔽。
这意味着：批量更新根变量 ≠ 全局实时刷新所有依赖处。如果某些组件内部重定义了变量，它们不会响应根节点的变更。
实操建议：
- 检查是否有组件级
--xxx声明，尤其来自第三方 UI 库（如 Element Plus、Ant Design Vue 的 scoped 样式） - 调试时用浏览器开发者工具的“Computed”面板，看具体元素最终解析出的变量值，而不是只盯
:root - 避免在 JS 中模拟 CSS 继承逻辑（比如遍历所有元素再 setProperty），成本高且不可靠
批量更新时如何避免 FOUC 或闪烁？
连续调用多次 setProperty() 可能触发多次样式重排（layout），尤其在低端设备上，用户可能看到短暂样式错乱（比如按钮颜色分两帧变）。
这不是浏览器 bug，而是渲染机制：每次 style 修改都可能被当作独立样式变更处理。
实操建议：
- 把所有要更新的变量收集到一个对象里，一次性遍历设置，比分散调用好
- 如需强一致性，可用
requestAnimationFrame()包裹整个更新块，确保在下一帧统一提交 - 极端情况（如主题切换）可先加
document.documentElement.classList.add('theme-updating')，配合 CSS.theme-updating * { transition: none !important; }临时禁用过渡
真正麻烦的不是怎么设变量，而是变量被谁用了、在哪被覆盖了、以及更新后哪些地方根本没反应——这些得靠 DevTools 的“Rules”和“Computed”面板交叉验证，光靠 JS 代码没法自动发现。
