map-merge不支持动态合并，必须在@import "bootstrap/scss/variables"前执行，否则新增主题色不会生成对应类；它只做单层覆盖，嵌套需手动递归；合并后需确保样式文件实际引用新map并触发编译。
map-merge 不支持动态合并多套主题配置，它只做单层覆盖，且必须在变量初始化前执行——写在 @import "bootstrap/scss/variables" 之后就完全无效。
为什么 map-merge 合并后新增主题色不生成对应类？
根本不是函数用错了，而是执行时机错位。Bootstrap 的 _variables.scss 会在导入时立刻用原始 $theme-colors 初始化 $primary、生成工具类名列表（如 .btn-brand），后续任何 map-merge 都只是改了个“副本”。
- 必须严格按顺序：
@import "bootstrap/scss/functions"→ 执行$theme-colors: map-merge($theme-colors, ("brand": #2563eb))→@import "bootstrap/scss/variables" - 如果用 Vite，还需确认
css.preprocessorOptions.sass.sourceMap: true已启用，否则调试时看不到 SCSS 行号 - Webpack 用户要检查
sass-loader和css-loader的 sourcemap 配置是否链路完整
嵌套主题 map 合并时子键全丢，是 bug 吗？
不是 bug，是 map-merge 的设计行为：遇到同 key 的 map，直接整体替换，不递归比对内部键。比如：
$themes: (dark: (bg: #0f172a, text: #f1f5f9));<br>$new: (dark: (text: #e2e8f0));<br>$merged: map-merge($themes, $new); // 结果中 dark 只剩 text，bg 彻底消失
- 若真需深度合并，得手写递归函数，用
type-of()判断值类型，是 map 就再调一次map-deep-merge - 但更推荐避免嵌套：把状态色拆成独立变量（如
$btn-primary-hover），或保持$theme-colors扁平，只存语义键（primary、brand） - 组件内状态样式（hover/disabled）应由 mixin 显式控制，而非塞进主题 map 里
合并完 CSS 里还是没新样式，漏了哪步？
map-merge 只负责更新 map 数据，不自动触发样式生成。所有新键值必须被实际引用才能产出 CSS。
- Bootstrap 工具类依赖
_utilities.scss主动遍历$theme-colors；你得确认该文件确实读到了你合并后的新 map - 自定义规则必须手动
@each $name, $color in $theme-colors，并在循环体内用map-get($theme-colors, $name)取值，不能硬编码 - 若用了封装的
theme-val("brand")函数，要检查它内部是否读取的是你修改后的$theme-colors，而不是旧副本 - JS 切换
document.documentElement.setAttribute('data-theme', 'dark')前，CSS 里必须已存在[data-theme="dark"]对应的规则块
最易忽略的一点：SCSS map 是编译期结构，所谓“动态”仅指开发时重编译，不是运行时 JS 可修改的对象；所有主题切换逻辑必须靠 [data-theme] 选择器 + CSS 变量驱动，而不是幻想靠 JS 调用某个 Sass 函数来 merge。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
