document.documentelement.style.setproperty()是设置css变量的唯一可靠方法，必须带--前缀且值为字符串；读取需用getcomputedstyle().getpropertyvalue()并trim；批量设置应避免循环调用，优先用object.entries或拼接csstext；变量作用域遵循继承规则，局部设置会覆盖全局。
document.documentElement.style.setProperty() 是唯一可靠写法
直接用 document.documentElement.style.setProperty()，别想用 element.style.--color = 'red' 这种写法——语法错误，浏览器会报 Invalid left-hand side in assignment。CSS 变量必须走 setProperty() 接口，且第一个参数必须带 -- 前缀，第二个参数必须是字符串（哪怕传数字也得转成 '16px'）。
常见静默失败原因：
• 漏掉双短横线，写成 'primary-color'
• 传了数字 16 而不是字符串 '16px'
• DOM 还没挂载就调用（比如脚本放在 里没加 defer 或监听 DOMContentLoaded）
读取变量值不能靠 element.style.getPropertyValue()
element.style.getPropertyValue() 只查内联样式，对定义在 :root 里的变量完全无效。真要读当前生效值，必须用 getComputedStyle(document.documentElement).getPropertyValue('--color')，注意返回值前后可能带空格，建议接 .trim()。
刚设完立刻读大概率为空——这不是 bug，是 CSSOM 更新延迟。如果逻辑依赖读取结果，得包一层 requestAnimationFrame：
document.documentElement.style.setProperty('--bg', '#1a1a1a');
requestAnimationFrame(() => {
console.log(getComputedStyle(document.documentElement).getPropertyValue('--bg').trim()); // ✅
});
批量设置别循环调用 setProperty
连续调用多次 setProperty() 会触发多次样式计算，动画或高频交互场景下容易掉帧。推荐用 Object.entries() 批量写入，或者更彻底地拼 cssText：
- 安全批量写法：
Object.entries(theme).forEach(([k, v]) => document.documentElement.style.setProperty(k, v)) - 高性能写法：把所有变量拼成字符串，一次性赋给
document.documentElement.style.cssText += ';--color:#fff;--size:1rem;'（注意别覆盖已有内联样式） - 避免用
style.cssText = '...'全量重写，会清掉其他内联样式
作用域和优先级容易被忽略
CSS 变量不是全局“覆盖”，而是按作用域继承。你在 :root 设的变量，会被所有后代元素继承；但某个卡片组件自己写了 cardEl.style.setProperty('--bg', '#f9fafb')，那它内部的 var(--bg) 就取这个局部值，document.documentElement 的修改对它无效。
切换主题时最容易踩的坑：
• 页面里存在局部 style="--color: red" 的元素，导致主题色不统一
• 某些第三方组件内联设置了同名变量，绕过了你的主题逻辑
• @supports (color: var(--c)) {} 降级规则没配，老浏览器直接白屏
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
