CSS自定义属性（即“HTML变量”）是主题切换的载体而非开关，需通过动态修改变量值或切换预设类名实现主题切换；它以--开头声明于:root等选择器中，须配合var()在CSS中使用，不能直接作HTML属性。
CSS 自定义属性（即常说的“HTML 变量”）本身不切换主题，它只是主题切换的载体；真正切换主题靠的是动态修改这些变量的值，或切换预设的 CSS 类名。
什么是 HTML 变量？它和 CSS 变量是一回事
所谓“HTML 变量”其实是误称——标准叫法是 CSS 自定义属性，写在 :root 或任意选择器里，以 -- 开头，例如：--primary-color: #3b82f6;。它必须配合 var(--primary-color) 在 CSS 中使用，不能直接在 HTML 标签上当属性用（比如 <div data-color="..."> 不算）。
<p>常见错误现象：</p>
<ul>
<li>把 <code>data-theme="dark" 当成“变量”，但它只是个标记，不自动影响样式
--bg: white; 却没在任何地方用 background-color: var(--bg);，结果毫无效果document.documentElement.style.getPropertyValue('--bg') 前没确认该变量是否已声明（返回空字符串）主题切换的两种主流做法：类名切换 vs 变量重写
两者都依赖 CSS 自定义属性，但控制逻辑不同，适用场景也不同：
立即学习“前端免费学习笔记（深入）”；
-
类名切换：提前写好
.theme-dark { --bg: #111; --text: #eee; }，JS 切换document.documentElement.classList.toggle('theme-dark')。兼容性好，适合多主题且 CSS 规则较复杂的情况 -
变量重写：JS 直接调用
document.documentElement.style.setProperty('--bg', '#111')。更灵活，适合运行时动态计算颜色（如从用户上传图片提取主色），但大量 setProperty 可能触发重排 - 混合用法也常见：先用类名加载基础主题，再用 setProperty 微调个别变量（比如字体大小缩放）
容易被忽略的细节：作用域、继承与性能
CSS 自定义属性 是普通 CSS 属性，遵循层叠和继承规则。这意味着：
- 在
:root声明的变量全局可用，但在子元素选择器里重写会覆盖（例如article { --text: red; }），这点和 JS 全局变量完全不同 - 如果主题切换后部分区域没变色，大概率是 selector 优先级不够，或者变量没被该元素继承（比如
button默认不继承--text，得显式写color: var(--text);） - 频繁调用
setProperty修改同一变量（如做渐变过渡）不会自动触发 CSS transition，需配合transition: background-color 0.3s等具体属性，而非transition: --bg 0.3s（无效）
最常出问题的地方不是“怎么写变量”，而是忘了检查变量是否真被用到了样式里，以及没意识到类名切换和变量重写本质是两套控制路径——混用时容易互相覆盖却难以排查。
