直接调用 document.documentelement.style.setproperty('--color-primary', '#3b82f6') 即可修改 css 变量，前提是变量定义在 :root 或对应元素上；注意语法合法、作用域匹配、dom 已挂载、前缀双短横线，且 ie 不支持。
如何用 setProperty 修改 CSS 变量
直接改 document.documentElement.style.setProperty('--color-primary', '#3b82f6') 就行，前提是变量定义在 :root 或目标元素上。CSS 变量本质是自定义属性，JS 通过 style.setProperty 操作的就是这层“属性”，不是真实 CSS 规则。
常见错误是写成 element.style.--color-primary = 'red' —— 这语法非法，浏览器直接报 Invalid left-hand side in assignment；也有人试图用 cssText 覆盖整个 style 字符串，结果把其他内联样式全清掉了。
- 只对已挂载到 DOM 的元素生效（
document.body未 append 前调用会静默失败） - 变量名必须带两个短横线前缀，比如
--spacing-md，不能漏掉或写成单横线 - 如果变量在某个组件元素上定义（如
.card { --bg: white; }），就得调用cardEl.style.setProperty('--bg', 'black')，不能只动:root
为什么 setProperty 不触发重排但可能触发重绘
CSS 变量本身不直接控制布局，所以改它通常不会导致 layout（重排），但会影响 paint（重绘）—— 比如改了 --text-color，浏览器得重新绘制文字；改了 --box-shadow，得重绘阴影区域。
性能敏感场景下，频繁调用 setProperty 改同一个变量（比如滚动中实时更新 --scroll-y），仍可能造成掉帧。这不是方法的问题，而是浏览器要不断计算依赖该变量的样式结果。
- 避免在
requestAnimationFrame外高频调用（如mousemove里没节流就设变量） - 批量修改多个变量时，用一次
Object.entries(vars).forEach(...)比循环多次setProperty稍好，但差异极小，别过度优化 - 注意变量是否被
will-change提前声明过，没声明的话，首次使用新值可能有微小延迟
getPropertyValue 读不到变量值？检查作用域和拼写
读不到通常不是 JS 错，而是 CSS 变量根本没生效：要么没定义，要么定义在父级但当前元素没继承，要么拼错了名字（大小写敏感、多空格、少横线）。
例如 getComputedStyle(document.documentElement).getPropertyValue('--COLOR-PRIMARY') 返回空字符串，因为定义的是 --color-primary；又或者变量写在 .theme-dark 选择器里，但当前根元素没这个 class，自然取不到。
- 读取前先确认变量是否真存在于 computed style 中：
console.log(getComputedStyle(document.documentElement))，展开看有没有对应 key - 如果变量由 JS 动态注入（比如通过
insertRule插入 CSSOM），需等样式表解析完成再读，否则返回空 - 不要依赖
element.style.getPropertyValue读取非内联设置的变量值——它只查style属性，不查 computed 结果
兼容性与 SSR 场景下的 fallback 注意点
IE 完全不支持 CSS 变量，setProperty 在 IE 里存在但无效；现代浏览器都 OK，包括 iOS Safari 9.3+。真正容易出问题的是服务端渲染（SSR）：Node.js 环境没有 document，直接执行 document.documentElement.style.setProperty 会报 ReferenceError: document is not defined。
- SSR 中必须加运行时判断：
if (typeof document !== 'undefined') { ... } - 需要降级方案时，别只靠 JS 设置变量，应在 HTML 模板里预设默认值，比如
- 某些构建工具（如 Vite + Vue SFC）会在编译期把
var(--x)替换为 fallback 值，这时 JS 改变量可能被静态替换覆盖，需关掉相关插件或改用env()等替代方案
最麻烦的其实是变量链式依赖：A 变量用 B，B 用 C，C 是 JS 设置的——中间任一环没生效，整条链就断了，调试时得一层层查 computed style，而不是只盯 JS 那一行。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
