$theme-map 统一管理主题配置更可靠，因其防命名冲突、支持编译期 key 校验、可确定性遍历；离散变量易导致命名混乱、作用域污染、硬编码逃逸及拼错崩溃。
用 $theme-map 统一组织颜色、间距、断点等语义化模块，比零散变量更可靠——它天然防命名冲突、支持编译期 key 校验、可被 @each 确定性遍历，漏值、单位不一致、拼错变量名这类问题基本消失。
为什么不能继续用 $primary-color 这类离散变量？
中大型项目里，$primary-color、$spacing-sm、$radius-lg 这类变量会快速失控：
- 命名风格不统一：有人写
$sm-spacing，有人写$space-sm，IDE 搜索不到全部 - 作用域污染：两个组件都定义
$text-color，后引入的覆盖前一个，构建时无声失效 - 硬编码逃逸：按钮样式里直接写死
#333，没走变量，改主题时完全漏掉 - 拼错即崩溃：
map-get($colors, primary)拼成primar，返回null，CSS 规则不输出；但$primary-colr直接报Undefined variable，中断构建且报错位置常指向使用处而非定义处
定义 Map 时必须加引号，且嵌套访问要链式调用
$theme-map 的键名必须是字符串字面量，否则 Sass 解析为未定义变量：
$theme-map: (
"color": ("primary": #007bff, "text": #333),
"spacing": ("sm": 4px, "md": 8px),
"breakpoint": ("sm": 576px, "lg": 992px)
);取值时注意两点：
立即学习“前端免费学习笔记（深入）”；
-
map-get($theme-map, "color")✅；map-get($theme-map, color)❌（color被当变量） - 深层取值必须链式：
map-get(map-get($theme-map, "color"), "primary")✅；map-get($theme-map, "color.primary")❌（Sass 不支持路径字符串语法） - 建议封装函数：
@function theme($category, $key) { @return map-get(map-get($theme-map, $category), $key); }，调用theme("color", "primary")更安全
@each 遍历 Map 批量生成工具类，不是 for 循环
响应式类（如 .d-none-sm）、间距类（如 .p-md）、主题色 CSS 变量注入——这些必须靠 @each $name, $value in $map 实现全覆盖：
@each $name, $value in $breakpoints {
.d-none-#{$name} {
@media (max-width: $value - 1px) {
display: none;
}
}
}常见错误：
- 写成
@each $bp in $breakpoints→$bp实际是("sm": 576px)整个键值对，@media (max-width: $bp)编译失败 - 类名插值漏花括号：
.p-$name输出字面量$name；必须写.p-#{$name} - Map 存 rem 单位，但某处需 px：别提前转好存进 Map，应在
@each体内用math.div($value, 1rem)或自定义函数转换
复用同一 Map 驱动多属性，避免复制粘贴
一套 $spacing-map 可同时生成 padding、margin、gap 类，无需为每个属性建独立 Map：
@mixin generate-spacer($prop, $prefix) {
@each $name, $value in $spacing-map {
.#{$prefix}-#{$name} { #{$prop}: $value; }
}
}
<p>@include generate-spacer(padding, p);
@include generate-spacer(margin, m);关键点：
- 不要为 padding 单独建
$padding-map—— 它和$spacing-map是同一组值，复制即埋下不一致隐患 - Map 嵌套层级深时，务必加防御检查：
@if map-has-key($submap, $key)，避免null被意外输出为 CSS 值 - 如果项目已接入 CSS 自定义属性（
--color-primary），可用@each把$theme-map的值批量注入:root，实现编译期导出，供 JS 运行时读取
最易被忽略的是 Map 键名必须全用字符串字面量，以及嵌套访问必须链式调用——这两点不满足，map-get() 就会静默返回 null，而你可能在审查元素时才意识到某个颜色根本没生效。
