直接修改 CSS 变量不生效主因是层叠规则优先级冲突，需确保所有使用变量的样式选择器权重足够且无硬编码覆盖，同时 :root 必须声明默认值、合理利用 HSL、显式绑定富文本变量、内联脚本预设主题并同步 localStorage。
为什么直接改 document.documentElement.style.setProperty() 常常不生效
不是变量没设上，而是 CSS 层叠规则在“背后使坏”。setProperty('--primary', '#ff6b6b') 确实写进了 document.documentElement.style，但如果你的按钮样式是 .btn.active { color: #333; } 这种硬编码写法，它优先级高于 .btn { color: var(--primary); }，浏览器就直接用 #333，根本不去查变量值。
常见错误现象包括：主题切换后部分区域变色、部分不变、或者完全没反应。用开发者工具检查元素 computed style 中的 color 值，看它是否真来自 var(--primary) —— 如果显示的是实际颜色值（如 rgb(255, 107, 107)），说明变量被成功解析；如果显示的是 inherited 或 initial，大概率是选择器权重压过了变量引用，或该元素压根没声明 color: var(--primary)。
- 确保所有用到变量的 CSS 规则都写在 :root 定义之后，且没有更具体的选择器覆盖
- 避免在内联 style 里重复设置同名属性，比如
style="color: red"会盖过var(--primary) - 别在组件内部用
.card { --primary: red; }局部重定义——这会让后代继承这个局部值，破坏全局一致性
:root 里怎么定义变量才真正“全局可用”
把变量塞进 .theme-dark 类里，再靠 JS 切 class，听起来干净，但默认主题缺失时页面会白屏或文字消失——因为 :root 本身没定义任何值，var(--bg-color) 没 fallback 就是 transparent 或继承色。
正确做法是：所有基础变量必须在 :root 中声明默认值，再用 class 或媒体查询覆盖。例如：
立即学习“前端免费学习笔记（深入）”；
:root {
--bg-color: #ffffff;
--text-color: #333333;
--border-color: #e0e0e0;
--font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}
.theme-dark {
--bg-color: #121212;
--text-color: #eeeeee;
--border-color: #333333;
}
这样即使 JS 加载失败、class 没切上，页面也有可用样式。HSL 格式比 HEX 更推荐，比如 --primary: hsl(210, 70%, 55%)，后续能方便地生成 hsl(210, 70%, 40%) 作为深色模式主色，无需换色值体系。
编辑器内容区为啥不继承主题变量
contenteditable 区域插入的 HTML 片段（比如从 wangEditor5 导出的 <p><strong>加粗文本</strong></p>）不会自动继承父级 CSS 变量作用域——尤其当内容被序列化再反序列化时，变量上下文就丢了。
不能指望 inherit 或 currentColor 自动传递变量，它们不解析 var()。必须显式绑定：
- 给内容容器加 wrapper class，例如
.editor-content，并在其中声明所有需继承的变量引用：color: var(--text-color); background-color: var(--bg-color); border-color: var(--border-color); - 对富文本标签单独声明，比如
.editor-content strong { color: var(--text-color); }，否则浏览器默认<strong>是黑字，在深色背景下可能看不见 - 所有
var()都带 fallback，如color: var(--text-color, #333)，防止变量未定义时样式崩塌
用户手动切换主题时怎么避免闪屏和 localStorage 同步失效
闪屏本质是 DOM 渲染完成前主题还没加载好。等 DOMContentLoaded 再读 localStorage.getItem('theme')，用户已经看到默认主题一闪而过。
解决方法是在 <head> 里放一段内联脚本，HTML 解析阶段就执行：
<script>
const savedTheme = localStorage.getItem('theme');
if (savedTheme) {
document.documentElement.classList.add(savedTheme);
} else {
const darkPref = window.matchMedia('(prefers-color-scheme: dark)').matches;
document.documentElement.classList.add(darkPref ? 'theme-dark' : 'theme-light');
}
</script>
注意：用 document.documentElement.classList，不是 document.body —— 因为变量作用域从 :root 开始，class 加在 html 上才能确保所有后代正确继承。
写入时务必同步 localStorage：
- 点击切换按钮后，先
localStorage.setItem('theme', 'theme-dark')，再document.documentElement.classList.toggle() - 监听
storage事件，处理多标签页间主题同步（比如一个标签页切了深色，其他页也自动响应） - 别忽略
prefers-color-scheme回退逻辑——用户首次访问且未手动选择时，应尊重系统偏好
复杂点在于 fallback 顺序和 class 作用域层级：:root 必须有默认值，@media 和 .theme-xxx 是覆盖层，JS 只负责开关 class，不碰变量值本身。一旦漏掉某一层的 fallback 或 class 位置错，就会出现局部失色或闪屏。
