SCSS Map必须扁平定义，禁用变量拼接；应使用$colors: ("primary": #007bff, "surface": #ffffff)等字符串键名，配合map-get()安全取值、@each批量生成CSS变量与主题规则，确保可维护性与运行时切换能力。
SCSS Map 必须扁平定义，不能靠变量拼接取值
直接写 $primary-color、$secondary-bg 这类独立变量，主题一多就失控。Map 是唯一能结构化管理多主题颜色的方式，但必须用扁平键名，比如 $colors: ("primary": #007bff, "surface": #ffffff)，而不是嵌套过深的 ("light": ("primary": ...)) —— 后者会让 map-get 取值变复杂，还容易漏掉 sass:map 扩展依赖。
常见错误是试图用动态变量名拼接：$color-#{$name}，Sass 不支持运行时变量解析，编译直接报 Undefined variable。而 map-get($colors, "primary") 是类型安全的，IDE 能跳转，键不存在时返回 null 而非崩溃。
- 键名统一用小写+短横线（如
"text-muted"），避免空格或大写导致引用失败 - 所有主题共用同一组 key，比如
"bg"、"text"、"border"，否则 JS 侧map-get($theme-map, "text")会返回null - 不要在顶层 CSS 规则里直接调用
map-get，Sass 会报错；必须包在@mixin或@function里
用 @each + [data-theme] 自动生成多套选择器
手写 [data-theme="dark"] .btn { color: #f1f5f9; } 这种规则，3 个主题还能忍，5 个以上必然漏或写错。@each 是唯一可维护方式，核心是把主题名注入属性选择器，并保留父级上下文：
@mixin themeify {
@each $theme-name, $theme-map in $themes {
$theme-map: $theme-map !global;
[data-theme="#{$theme-name}"] & {
@content;
}
}
}
然后在组件中这样用：
立即学习“前端免费学习笔记（深入）”；
.btn {
color: map-get(map-get($themes, "light"), "text");
@include themeify {
color: map-get($theme-map, "text");
}
}
-
&保证选择器继承父级（如.btn），适合在 mixin 内复用 -
$theme-map: $theme-map !global是关键，否则$theme-map在@content块内不可见 - 别用
:root[data-theme]直接覆盖 CSS 变量——它会破坏组件内联样式优先级，导致color: var(--text-color) !important失效
必须导出为 CSS 自定义属性，SCSS 变量无法运行时切换
$primary 这类 Sass 变量在构建后就固化成死值，JS 改不了，也读不到。真正能动态换色的是 CSS 自定义属性：--color-primary。生成逻辑必须用 @each 遍历 Map 并拼出变量：
:root {
@each $key, $value in $colors {
--color-#{$key}: #{$value};
}
}
[data-theme="dark"] {
@each $key, $value in $dark-colors {
--color-#{$key}: #{$value};
}
}
注意两点：
- 变量名拼接必须用
--color-#{$key}，$key是字符串，不能带点号（如primary.text）否则被当成类名解析 - 必须给
:root提供默认值，否则首次渲染时var(--color-text)没 fallback，可能显示为透明或继承色 - JS 切换主题应调用
document.documentElement.setAttribute('data-theme', 'dark')，而非反复style.setProperty单个变量——后者无法批量同步所有关联色
系统偏好适配要靠 prefers-color-scheme + JS 监听，不是 SCSS 的事
SCSS 本身无法响应系统主题变化，@media (prefers-color-scheme: dark) 规则必须手动写两套完整变量声明，浏览器不会“合并”或“继承”：
@media (prefers-color-scheme: light) {
:root {
--color-bg: #ffffff;
--color-text: #1e293b;
}
}
@media (prefers-color-scheme: dark) {
:root {
--color-bg: #0f172a;
--color-text: #f1f5f9;
}
}
更关键的是兜底逻辑：用户可能手动切换主题，或系统未提供偏好（如旧版 Windows）。必须用 JS 监听并同步 data-theme：
- 监听代码得放在
DOMContentLoaded后，否则document.documentElement可能未就绪 - 初始化时就要调用一次
matchMedia('(prefers-color-scheme: dark)').matches，避免首屏闪白/闪黑 - 仅靠媒体查询不够——如果用户点了“手动切暗色”，但没同步
data-theme，那组件里[data-theme="dark"]规则根本不会生效
最易被忽略的点：CSS 变量声明必须成对、完整、显式，漏一个，对应样式就回退到初始值，而且这种问题在 DevTools 里很难一眼看出。
