CSS自定义属性是作用域可控的运行时变量，区别于class切换：前者改一处值全局响应更新，后者需手动维护多套规则；它支持级联继承与局部覆盖，而class方案无法实现。
什么是CSS自定义属性，和普通class切换有什么区别？
CSS自定义属性（即 --primary-color 这类以 -- 开头的变量）本质是作用域可控的运行时变量，不是编译期静态值。它和用多个 theme-dark/theme-light class 切换的根本差异在于：前者只需改一处值，所有依赖它的颜色、间距、阴影等都会响应式更新；后者要手动维护多套规则，容易漏改或冲突。
关键点在于：自定义属性支持级联和继承，:root 定义的是全局默认值，但你完全可以在某个组件内部用 div { --primary-color: red; } 覆盖，不影响其他区域——这种局部覆盖能力是纯 class 方案做不到的。
如何声明和批量引用主题变量？
别把所有颜色都零散写在 :root 里。按语义分组更易维护：
:root {
/* 基础色板 */
--color-primary: #007bff;
--color-secondary: #6c757d;
--color-success: #28a745;
/* 衍生色 */
--color-primary-hover: #0056b3;
--color-primary-active: #004080;
/* 中性色 */
--color-bg: #ffffff;
--color-text: #333;
--color-border: #e9ecef;
}然后在组件中直接引用，比如按钮背景色写成 background-color: var(--color-primary);，悬停状态用 background-color: var(--color-primary-hover);。注意：不要在 var() 里嵌套另一个 var()（如 var(--color-primary-hover) 不能依赖 var(--color-primary) 动态计算），浏览器不支持运行时表达式。
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
立即学习“前端免费学习笔记（深入）”；
怎么用JavaScript一键切换主题？
核心就是动态修改 :root 下的变量值，而不是切换 class：
- 用
document.documentElement.style.setProperty('--color-primary', '#ff6b35');直接覆盖 - 避免用
document.body.className = 'theme-dark'这类方式，否则无法触发 CSS 变量的级联更新 - 切换后无需重绘 DOM，所有
var()引用会自动响应，但要注意：如果某元素设置了background-color: #007bff（硬编码值），它不会变 - 推荐把整套主题变量封装成对象，便于复用：
const themes = { blue: { '--color-primary': '#007bff', '--color-bg': '#ffffff' }, purple: { '--color-primary': '#6f42c1', '--color-bg': '#f8f9fa' } };
为什么切换后部分样式没更新？常见坑有哪些？
最常踩的坑是：变量名拼错、作用域不对、或用了不支持的 fallback 写法。
-
var(--color-prmiary)少了个r—— 浏览器静默忽略，回退到继承值或初始值，很难排查 - 在
@media查询里重新定义:root变量，但忘了加!important或作用域层级不够，导致未生效 - 写了
color: var(--text-color, black);，但--text-color在当前作用域根本没定义，此时 fallback 生效，看起来“正常”，实则变量未被使用 - SSR 场景下，服务端渲染时
:root变量还没被 JS 注入，首屏可能显示默认色，需在 HTML 模板中预设一组变量值
真正要让主题切换稳，得确保所有颜色/尺寸都来自 var()，且每个变量都有明确来源和 fallback；变量名统一用 kebab-case，避免大小写混用。别的先不管，先把按钮、输入框、卡片这些高频组件的 border-color、background、color 全换成变量再说。
