只能用 document.documentElement.style.setProperty()，因为全局 CSS 变量绑定在 :root（即 <html> 元素）上，只有操作其 style 对象才能使变量透传至整个文档树；其他方式如 body 或任意元素调用仅限局部生效。
必须用 document.documentElement.style.setProperty()，其他写法基本都失效或只局部生效。
为什么只能用 document.documentElement.style.setProperty()
因为全局 CSS 变量的运行时作用域绑定在 :root（即 <html> 元素）上，只有操作它的 style 对象，才能让变量值透传到整个文档树。写成 document.body.style.setProperty() 或随便找一个元素调用，变量只会挂载在那个元素的内联样式里，后代组件读不到。
-
document.documentElement对应:root，是唯一能触发全局更新的入口 -
document.body.style.setProperty('--color', 'red')不报错，但.header、.sidebar等非body后代的元素根本不会继承这个值 - Shadow DOM 内部调用时，需显式向 host 透传，否则子组件主题不响应
setProperty() 的参数必须严格合规
漏一个字符、错一个类型，就会静默失败——浏览器既不报错也不生效。
- 变量名必须带
--前缀：'--theme-bg'✅，'theme-bg'❌，'-theme-bg'❌ - 值必须是字符串：
'16px'✅，16❌，null❌，undefined❌ - 大小写敏感：
'--Color-Primary'和'--color-primary'是两个变量 - DOM 必须已挂载：脚本放在
<head>里没加defer或没监听DOMContentLoaded，调用会白执行
读取值不能靠 element.style.getPropertyValue()
它只查内联样式，对 :root 里定义的变量完全无效。真要读当前生效值，得走计算样式。
立即学习“前端免费学习笔记（深入）”；
- 读全局变量：
getComputedStyle(document.documentElement).getPropertyValue('--theme-bg') - 返回值前后可能带空格，建议接
.trim()，比如" #121212 "→"#121212" - 刚设完立刻读大概率为空——这不是 bug，是 CSSOM 更新延迟，可稍后用
requestAnimationFrame重试 - 返回空字符串
""（不是null或undefined），别用== null判空
批量修改多个变量时别循环调用 setProperty
一次切主题常要改 10+ 个变量，逐个调用不仅啰嗦，还可能触发多次样式重计算，造成短暂闪烁或卡顿。
- 推荐用
Object.entries(vars).forEach(([k, v]) => root.style.setProperty(k, v)) - 避免用
element.setAttribute('style', cssText)全量覆盖，会清掉其他内联样式 - 超过 20 个变量时，合并设置比逐个调用更稳妥，但差异极小，别过度优化
- 高频场景（如滚动中实时更新
--scroll-y）务必节流，否则容易掉帧
最易被忽略的是作用域匹配和 DOM 挂载时机：变量定义在 :root，JS 就必须动 document.documentElement；脚本提前执行，再对的写法也拿不到节点。
