SCSS无法实现无刷新暗黑模式切换，因其变量在编译时即被替换为静态值；真正实现运行时切换的是CSS自定义属性（如--bg）配合JS动态修改data-theme属性并确保:root中声明、var()带回退值、初始化时机合理。
不能直接在 SCSS 中“实现”无刷新暗黑模式切换——SCSS 是编译时工具，生成的是静态 CSS；真正负责运行时切换、响应用户操作、避免闪动的，是 CSS 自定义属性 + JS 的组合。SCSS 在这里只起辅助作用：生成初始变量、组织主题映射、避免硬编码。
为什么不能靠 SCSS 变量做暗黑模式切换
SCSS 变量（如 $primary-color）在构建时就被替换成具体值，输出到 CSS 文件里就没了。你改不了它，JS 也读不到它。所谓“切换”，本质是让同一份 CSS 规则在不同上下文中解析出不同颜色/尺寸/背景，这只能靠运行时可变的 --theme-bg 这类自定义属性来承载。
常见错误现象：
– 写了一堆 @if $theme == 'dark' { ... }，结果编译完只有 light 版本生效
– 在 JS 里试图 document.documentElement.style.setProperty('--primary', 'red')，但发现没效果——因为 CSS 里压根没写 var(--primary)，全是 SCSS 编译死的 #409eff
SCSS 应该只干三件事：声明映射、生成基础变量、导出 token
把 SCSS 当作“主题配置生成器”，而不是“切换控制器”。例如：
立即学习“前端免费学习笔记（深入）”；
// _themes.scss
$themes: (
light: (
bg: #ffffff,
text: #333333,
border: #e0e0e0,
),
dark: (
bg: #1e1e1e,
text: #e0e0e0,
border: #333333,
)
);
// 批量生成 :root 中的 CSS 自定义属性
@each $theme, $map in $themes {
:root[data-theme='#{$theme}'] {
@each $key, $value in $map {
--#{$key}: #{$value};
}
}
}
这样生成的 CSS 里就有：
:root[data-theme='light'] { --bg: #ffffff; --text: #333333; }
:root[data-theme='dark'] { --bg: #1e1e1e; --text: #e0e0e0; }
后续所有组件样式都用 var(--bg)，不用再碰 SCSS 条件判断。
JS 切换必须原子化 + 避免闪动
关键不是“怎么切”，而是“什么时候切、切什么、怎么兜底”。容易踩的坑：
- 只改
data-theme属性，不触发 Bootstrap 等库的更新逻辑 → 结果样式卡在旧值（见 Bootstrap 文档要求调用bootstrap.Theme.getOrCreateInstance().update()） - 在
DOMContentLoaded后才设置 theme → 用户先看到亮色，再闪成暗色 - 忽略系统偏好，也不读 localStorage → 用户上次选了 dark，刷新后又变回 light
推荐初始化写法：
// 优先读 localStorage， fallback 到 prefers-color-scheme
const saved = localStorage.getItem('theme');
const systemPrefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
const initial = saved || (systemPrefersDark ? 'dark' : 'light');
document.documentElement.setAttribute('data-theme', initial);
// 如果用了 Bootstrap 5.3+，立刻跟一句：
// bootstrap.Theme.getOrCreateInstance(document.documentElement).update();
CSS 自定义属性必须参与继承与过渡
仅靠 var(--bg) 不够，要让它真正“动起来”：
- 确保父元素（通常是
:root或html）设了--bg，子元素才能继承并使用var(--bg) - 如果想加淡入淡出，得对具体属性加 transition：
background: var(--bg); transition: background 0.3s ease;—— 注意：不是对--bg本身加 transition（CSS 变量不支持直接过渡），而是对消费它的属性加 - 避免在伪类里重复写整套变量，比如
:hover { --bg: #222 }—— 这会覆盖继承链，且不可预测；应统一在[data-theme='dark']下定义，hover 仅控制 opacity / transform 等行为
最易被忽略的一点：深色模式不只是换个背景色。文字对比度、图标颜色、阴影强度、边框透明度，全得重新校准。WCAG 要求正文文本与背景对比度 ≥ 4.5:1，#1e1e1e 上用 #e0e0e0 是合格的，但用 #aaaaaa 就不合格——这些细节无法靠 SCSS 自动生成，必须人工验证。
