element.style.setProperty 是修改 CSS 变量最可靠方式，需确保作用域匹配（如 :root 或元素自身），读取时注意节点一致性和时机，批量更新宜循环调用 setProperty，主题切换优先用 class 控制。
直接用 element.style.setProperty 改 CSS 变量最可靠
原生 JS 修改 CSS 变量，style.setProperty 是唯一推荐方式。它绕过内联样式的字符串拼接，避免大小写敏感、分号遗漏、单位缺失等常见翻车点，且能正确触发 CSS 自定义属性的级联和计算。
常见错误是试图用 element.style['--primary-color'] = '#3b82f6' 或 element.style.setProperty('--primary-color', '#3b82f6') 却没生效——问题往往出在作用域：CSS 变量必须设置在「能被目标元素继承或匹配到」的节点上，通常是 :root 或该元素自身。
- 改全局变量 → 用
document.documentElement.style.setProperty('--color-bg', '#f9fafb') - 改局部变量 → 用
myCard.style.setProperty('--shadow-size', '8px')（前提是该元素声明了--shadow-size或其父元素已定义且可继承） - 值里带函数（如
hsl()、var()）要确保语法合法，setProperty不做校验，错值会导致变量退回到初始值或unset
getComputedStyle 读不到刚设的变量？先确认作用域和时机
用 getComputedStyle(el).getPropertyValue('--my-var') 读不到最新值，大概率不是 API 问题，而是你设变量的位置和读的位置不匹配。例如在 :root 设了 --theme，却去某个子元素上调用 getComputedStyle(child) 读——只要该子元素没覆盖这个变量，就能读到；但如果子元素自己 style.setProperty('--theme', 'dark') 过，那读的就是它自己的值。
另一个典型坑是「同步读取时机」：在 requestAnimationFrame 外立刻读，有时会拿到旧快照，尤其涉及动画或布局触发时。稳妥做法是：
立即学习“Java免费学习笔记（深入）”；
- 确保
setProperty和getComputedStyle针对同一个 DOM 节点 - 如果依赖样式计算结果（比如根据变量算尺寸），加一层
requestAnimationFrame再读 - 调试时用浏览器开发者工具的「Computed」面板看「Declared in」来源，比代码更准
批量更新多个 CSS 变量别连写 setProperty，用 cssText 更快但有风险
一次设 5 个变量，调 5 次 setProperty 没问题，但性能略低（每次触发样式重新计算）。想提速可以用 element.style.cssText += '; --a:1; --b:2; --c:3;'，但要注意：
-
cssText是全量覆盖，会清空之前通过setProperty或内联 style 设置的其他属性（包括非变量，比如color、display） - 拼接字符串容易引入语法错误，比如漏分号、多空格、单引号双引号混用导致解析失败
- 无法做类型校验，
setProperty至少能帮你把数字转成字符串，cssText全靠手写
真要批量更新，更稳的方式是封装一个函数，内部循环调 setProperty，再加个 el.offsetHeight 强制同步（仅必要时）。
动态主题切换时，CSS 变量 + class 切换比纯 JS 更新更健壮
纯靠 JS 批量 setProperty 切主题，代码易膨胀、难维护、不利于 SSR 和缓存。实际项目中，更推荐「CSS 定义主题，JS 控制 class」：
- 在 CSS 里写好
.theme-dark { --color-text: #e5e7eb; --color-bg: #111827; }和.theme-light { --color-text: #1f2937; --color-bg: #ffffff; } - JS 只需
document.documentElement.classList.toggle('theme-dark') - 变量更新由浏览器自动完成，无竞态、无遗漏、支持媒体查询联动（比如
@media (prefers-color-scheme: dark)）
只有当主题需要用户实时微调（如亮度滑块）、或变量值来自 API 动态计算时，才必须走 setProperty。这时候记得把变量名和逻辑抽离成配置对象，别散落在事件回调里。
CSS 变量本身没有“监听”机制，所有“响应式更新”都依赖属性变更触发的重绘；真正容易被忽略的是：变量值变更不会触发 resize、scroll 或自定义事件，如有依赖，得手动 dispatch。
