深色模式变量必须在 :root 中声明才能被 JS 或媒体查询动态覆盖，嵌套选择器无效；正确做法是用 :root 定义默认值，再通过媒体查询或类名重写同一组变量。
深色模式变量必须用 :root 声明，否则 CSS 变量无法被 JS 或媒体查询动态覆盖
很多人直接在 .dark 类里定义 --color-bg: #121212，结果发现切换主题后样式不生效——根本原因是 CSS 变量作用域问题。浏览器只认顶层 :root 下的变量，嵌套选择器里的声明不会覆盖它。
正确做法是：在顶层 :root 中定义默认（浅色）值，再用媒体查询或类名重写同一组变量：
:root {
--color-bg: #ffffff;
--color-text: #333333;
}
@media (prefers-color-scheme: dark) {
:root {
--color-bg: #121212;
--color-text: #e0e0e0;
}
}
.dark-theme :root {
--color-bg: #121212;
--color-text: #e0e0e0;
}
注意：.dark-theme :root 这种写法依赖 HTML 根节点加了 class="dark-theme"，适合 JS 主动切换；@media 适合系统级自动响应。
Sass 中用 @each 批量生成深色变量，避免手写重复
手动维护两套变量极易出错，尤其颜色层级多时。Sass 的 @each 可以把颜色映射抽象成 map，一次生成所有变量：
$colors-light: (
'bg': #ffffff,
'text': #333333,
'border': #e0e0e0,
);
$colors-dark: (
'bg': #121212,
'text': #e0e0e0,
'border': #333333,
);
@function generate-vars($map, $prefix: '') {
$vars: '';
@each $key, $value in $map {
$vars: $vars + '--#{$prefix}#{$key}: #{$value}; ';
}
@return $vars;
}
:root {
#{generate-vars($colors-light)};
}
.dark-theme :root {
#{generate-vars($colors-dark)};
}
关键点：
立即学习“前端免费学习笔记（深入）”；
-
generate-vars()返回字符串，需用#{...}插入 CSS 规则中 - 变量名带前缀（如
$prefix: 'color-'）可避免命名冲突 - 不要在
@each里直接写--var: value，Sass 编译会报错
用 @if 切换 Sass 编译时主题，适用于构建时固定主题
如果项目只需打包一份深色 CSS（比如纯深色版 App），不必运行时切换，可用 @if 控制编译输出：
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
$theme: 'dark'; // 或 'light'
@if $theme == 'dark' {
:root {
--color-bg: #121212;
--color-text: #e0e0e0;
}
} @else {
:root {
--color-bg: #ffffff;
--color-text: #333333;
}
}
这种方案的好处是零运行时开销，但缺点也很明显：
- 无法响应系统偏好或用户手动切换
- 需构建两次才能同时支持亮/暗两套 CSS
- 变量名不能复用，容易和运行时方案混淆
JS 切换主题时，document.documentElement.classList 必须操作根节点
很多人在 body 上加 dark 类，然后写 .dark .card { ... } ——这能工作，但无法影响 :root 下的变量。CSS 变量只响应 :root 或其伪类（如 :root.dark）的声明。
正确 JS 写法：
function setTheme(theme) {
document.documentElement.classList.remove('light', 'dark');
document.documentElement.classList.add(theme); // theme 是 'light' 或 'dark'
}
// 调用
setTheme('dark');
对应 Sass：
:root.light {
--color-bg: #ffffff;
}
:root.dark {
--color-bg: #121212;
}
注意：:root 就是 html 元素，所以操作 document.documentElement 才能命中。
真正麻烦的是变量继承链和 fallback 处理——比如某个组件用了 color: var(--color-text, #333)，但深色模式下 --color-text 没定义，就会退回到 #333，而不是你期望的 #e0e0e0。每个 var() 都得显式写 fallback，这点容易漏。
