直接修改 document.documentElement.style.setProperty 即可，但90%失效源于变量未继承、作用域错误或被内联样式覆盖；element.style.setProperty仅影响内联样式，CSS变量须定义在:root或选择器中才生效。
直接改 document.documentElement.style.setProperty 就行，但 90% 的失效不是方法错，而是变量没被正确继承、作用域写错，或者被内联样式覆盖了。
为什么 element.style.setProperty 不生效
常见错误是拿一个普通 DOM 元素（比如 document.querySelector('.card')）直接调用 style.setProperty，结果颜色纹丝不动。因为 element.style 只读写内联样式（即 style="..." 属性），而 CSS 变量必须写在 :root 或某个选择器规则里才有效。
- 要改全局主题色，必须用
document.documentElement.style.setProperty('--primary-color', '#3b82f6') - 要改某组件局部主题（比如只影响一个卡片），得先确保该卡片元素上声明了变量，例如
.card { --bg-color: #f9fafb; }，再用cardElement.style.setProperty('--bg-color', '#1f2937') - 变量名必须带两个短横线前缀，
'--color-primary'对，'color-primary'或'-color-primary'都无效 - 值必须是字符串，
'24px'、'0.8'、'#1a1a1a'都行，但传数字24或0.8会静默失败
变量更新了，但页面颜色没变
不是 JS 没执行，而是 CSS 层级或引用方式出了问题。浏览器确实更新了变量值，但样式没“用到它”。
- 检查目标元素的
computed styles，看background-color最终解析出来是不是你设的变量值（比如#3b82f6），而不是var(--primary-color)字面量本身 - 确认该元素或其任意父级没有显式声明同名属性（比如写了
background-color: red），这会直接覆盖var()的级联结果 - 如果用了
!important，var()无法对抗，得去掉或统一用变量控制 - 伪元素（如
::before）有时不会自动重绘，可加一行btn.offsetHeight触发重排（仅必要时）
如何安全地批量更新整套主题
单个 setProperty 容易漏、难维护；批量写入更可靠，也方便和 localStorage 同步。
使用约定式提交（Conventional Commits）生成标准化的 Git 提交信息。适用于以下场景： (1) 暂存更改时需要提交信息； (2) 审查 diff 时希望获得结构化摘要； (3) 编写 PR 描述或变更日志（changelog）条目； (4) 用户明确要求“为本次更改编写提交信息”。 该功能会分析已暂存/未暂存的 diff，并生成按类型（type）划分范围的提交信息。
- 把主题封装成对象，键名严格匹配变量名：
{ '--bg-color': '#111827', '--text-color': '#f9fafb' } - 用
Object.entries(theme).forEach(...)循环设置，避免手写多行重复代码 - 别在
:root外再定义同名变量（比如在.header里又写--bg-color），否则就近原则会让局部变量覆盖全局，导致切换混乱 - 深浅主题建议共用变量名，靠
[data-theme="dark"]选择器覆盖值，而不是新增一套--dark-bg-color，否则 JS 逻辑会指数级膨胀
移动端 Safari 上颜色延迟或不更新
iOS 15.4 之前版本对 CSS 变量重绘有优化缺陷，尤其在快速连续触发时。
- 避免在
touchstart立即调用setProperty，改用setTimeout(() => {}, 0)推进微任务队列 - 真机调试时别信肉眼判断，用
console.log(getComputedStyle(btn).backgroundColor)直接看最终计算值 - 确保按钮样式真正依赖
var(--btn-bg)，而不是被其他规则（比如媒体查询里的@media (prefers-color-scheme: dark)）抢先覆盖 - 如果用了
transition，记得在:root或[data-theme]规则里声明，不要只写在元素上，否则变量更新后过渡可能不触发
最常被忽略的一点：CSS 变量修改后，是否所有用到它的地方都真的“需要响应”？比如一个固定色的 icon SVG 填充写死为 #333，它就不会跟着 --text-color 变——这种硬编码节点，得手动同步或改用 currentColor。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
