<p>必须用 document.documentElement.style.setProperty 因为只有操作 html 元素的 style 才能修改全局 CSS 变量；其他元素仅影响自身内联样式，且需带 -- 前缀、传字符串值、避免 cssText 清空样式。</p>
document.documentElement.style.setProperty 为什么必须用这个写法
因为只有操作 document.documentElement.style 才能真正修改全局 CSS 变量的运行时值。写成 document.body.style.setProperty 或随便找一个元素调用，变量根本不会透传到整个页面——它只影响那个元素自身的内联样式，而 :root 是 html 元素的伪类，浏览器把这里设的变量当全局上下文处理。
常见错误包括：
- 漏掉双短横线前缀，比如传
'color-bg'而不是'--color-bg'，浏览器直接忽略 - 传入非字符串值，例如
16或null，setProperty会静默失败或清空变量 - 在 Shadow DOM 内部调用却没向 host 透传，导致子组件主题不响应
批量设置多个变量时别一个个调用 setProperty
一次切主题要改十几个变量，逐个 setProperty 不仅代码啰嗦，还可能触发多次样式重计算，造成短暂闪烁或卡顿。现代浏览器对批量更新有优化，但超过 20 个变量时仍建议合并。
推荐封装函数一次性写入：
立即学习“前端免费学习笔记（深入）”；
function setTheme(vars) {
const root = document.documentElement;
Object.entries(vars).forEach(([key, value]) => {
root.style.setProperty(key, value);
});
}
setTheme({
'--bg-color': '#121212',
'--text-color': '#e0e0e0',
'--border-color': '#333'
});
注意：cssText = '' 不能用，它会清空所有已有的内联样式；也不要手动拼接字符串赋值，容易引入 XSS 风险或语法错误。
为什么改了变量页面颜色却没变
最常见原因是样式里没真正“用上”变量，或者被更具体的规则覆盖了。比如写了 color: var(--text-color);，但某个按钮又单独加了 button { color: #333; }，后者优先级更高，主题切换就失效了。
排查要点：
- 打开开发者工具的 “Computed” 面板，看目标元素最终计算出的
color或background-color值是否真的来自var(--xxx) - 检查是否所有颜色、边框、阴影、SVG 填充、滚动条（
scrollbar-color）都统一用了var()，不能混用字面量 - 确认变量定义在
:root下，而不是某个 class 或组件选择器内部 - 如果用了
@media (prefers-color-scheme: dark)，记得里面也要完整重定义变量，不能只靠继承
localStorage 存什么、什么时候读、怎么防闪屏
只存一个字符串如 "dark" 是不够的——刷新后 JS 还得重新查一遍对应的颜色值，中间存在空白期。更可靠的是把整套变量值对象序列化存储，例如：
localStorage.setItem('theme', JSON.stringify({
'--bg-color': '#121212',
'--text-color': '#e0e0e0'
}));
但关键在于读取时机：必须在 HTML 开始解析时、任何样式表加载前就执行。否则浏览器先按默认主题渲染一帧，JS 再补，必然闪。
所以初始化脚本要放在 <head> 里，且不能加 defer 或 async：
<script>
const saved = localStorage.getItem('theme');
if (saved) {
const theme = JSON.parse(saved);
Object.entries(theme).forEach(([k, v]) => {
document.documentElement.style.setProperty(k, v);
});
}
</script>
别忘了同步 dataset 和 className，比如 document.documentElement.dataset.theme = 'dark'，方便后续用属性选择器做微调或调试。
