map-merge仅浅合并两个map且后值覆盖前值，必须在bootstrap变量初始化前执行，需先导入functions再修改$theme-colors最后导入variables，否则修改无效；浅合并不递归，嵌套map会整体替换；合并后须被实际引用才能生成css。
map-merge 不是“合并配置项”的万能胶水，它只做一件事：把两个 map 合成一个，且**后一个 map 的同 key 值会覆盖前一个**。真正决定它是否生效的，是执行时机和作用域——不是写对了函数就完事。
map-merge 必须在 Bootstrap 变量初始化前执行
你写了map-merge($theme-colors, ("brand": #2563eb)) 却没生成 .btn-brand？大概率是因为这行代码放在了 @import "bootstrap/scss/variables" 之后。
Bootstrap 的 _variables.scss 里会直接用 $theme-colors 初始化 $primary、$secondary 等变量，还会生成工具类名列表。一旦这步完成，后续改 $theme-colors 就只是改了个寂寞。
必须确保顺序：
$theme-colors: map-merge($theme-colors, ("brand": #2563eb));@import "bootstrap/scss/functions";@import "bootstrap/scss/variables";
$theme-colors 初始值来自 Bootstrap 自身，所以得先 @import "bootstrap/scss/functions"（提供 map-merge 函数），再改，再导入 variables。
合并时 key 冲突会导致意外覆盖
map-merge 是浅合并，不会递归处理嵌套 map。比如你有：
$themes: (light: (bg: #fff, text: #1e293b), dark: (bg: #0f172a, text: #f1f5f9));$new-themes: (dark: (text: #e2e8f0));$themes: map-merge($themes, $new-themes);
dark 整个被替换成新 map，bg 丢失了。这不是 bug，是设计如此。
需要深度合并时，得自己写递归 mixin 或用第三方函数（如 sass-maps 库里的 deep-merge），但多数主题场景用不上——直接保证所有主题 map 的 key 一致，靠 @each 分别生成规则更稳妥。
map-merge 后的 map 必须被实际引用
光合并完不等于样式就出来了。Bootstrap 工具类（如.text-primary）依赖 $theme-colors 被 _utilities.scss 读取；自定义主题切换则依赖你手动用 @each 遍历 $themes 生成 [data-theme="light"] { --text-color: #1e293b; } 这类规则。
常见漏点：
- 忘了在
@each $theme-name, $theme-map in $themes里用map-get($theme-map, text)取值，写了硬编码色值 - 合并后的
$theme-colors没传给 Bootstrap 的color-functions或自定义 mixin，导致theme-val(text)类函数取不到新值 - JS 设置
document.documentElement.setAttribute('data-theme', 'dark')，但 CSS 里没写对应[data-theme="dark"]选择器块
map-merge 就只是内存里一个没人理的 map。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
