map-merge不是万能函数，它只浅层覆盖且必须在@import "bootstrap/scss/variables"前执行，否则$theme-colors已被固化，新增颜色无法生成.btn-brand等类；嵌套map合并会丢失子键，因map-merge不递归；合并后需手动@each遍历并map-get取值，且确保新map被实际引用。
map-merge 不是“合并配置”的万能函数，它只做浅层覆盖，且执行时机错一位就全白干。
为什么 map-merge 后新增主题色没生成 .btn-brand 类
根本原因不是函数写错了，而是 map-merge 被放在了 @import "bootstrap/scss/variables" 之后。Bootstrap 的 _variables.scss 会立刻用原始 $theme-colors 初始化 $primary、生成工具类列表，并固化进后续所有逻辑。你改的只是个“副本”，编译器早就不认了。
必须严格按顺序写：
-
@import "bootstrap/scss/functions"（先加载map-merge函数） - 再执行
$theme-colors: map-merge($theme-colors, ("brand": #2563eb)) - 最后
@import "bootstrap/scss/variables"
为什么嵌套 map 合并后子键全丢了
map-merge 是浅合并：遇到同 key 的 map，直接整个替换，不递归比对内部键。比如你有 $themes: (dark: (bg: #0f172a, text: #f1f5f9))，再用 map-merge($themes, (dark: (text: #e2e8f0)))，结果 dark 里只剩 text，bg 消失了。
立即学习“前端免费学习笔记（深入）”；
这不是 bug，是设计行为。若真需要深度合并：
- 自己写递归函数，用
type-of()判断值类型，是 map 就再调一次map-deep-merge - 更稳妥的做法是避免嵌套：把状态色拆成独立变量，如
$btn-primary-hover: #0056b3，在 mixin 中显式引用 - 或保持
$theme-colors扁平，只存语义色名（primary、brand），状态样式由组件自身控制
为什么合并完 CSS 文件里还是没新颜色
光合并 $theme-colors 不等于样式自动出现。Bootstrap 工具类（如 .text-brand）依赖 _utilities.scss 主动遍历 $theme-colors 生成；自定义规则也得手动 @each 遍历并调用 map-get。
常见漏点：
- 忘了在
@each $name, $map in $theme-colors循环里用map-get($map, "brand")取值，写了硬编码色值 - 自定义 color function（如
theme-val("brand")）没读取你新合并的$theme-colors，仍查旧 map - 没确认
$theme-colors是否被实际传入了生成工具类的 mixin 或循环逻辑中
Vite 或 Webpack 下 Sass sourcemap 失效导致调试困难
修改 map-merge 逻辑后看不到 SCSS 行号跳转？大概率是 sourcemap 链路断了。Vite 必须同时开两个开关：css.devSourcemap: true 和 css.preprocessorOptions.sass.sourceMap: true；Webpack 则需确保 sass-loader、css-loader、MiniCssExtractPlugin 全部透传 sourceMap: true。
验证方法很简单：
- 打开浏览器 DevTools → Network → 刷页面 → 筛选
.css.map→ 看响应体里sources字段是不是项目内相对路径（如["theme.scss"]） - 如果
sources是空数组或含绝对路径（/Users/xxx/），说明 Dart Sass 编译时参数位置错了，或插件未适配@use别名路径
真正容易被忽略的是：map-merge 的生效与否，永远取决于它是否在变量被首次消费前完成赋值——不是语法对不对，而是“谁先看到这个值”。
