map-merge没生效的根本原因是执行时机错误：必须在@import "bootstrap/scss/functions"之后、@import "bootstrap/scss/variables"之前合并$theme-colors，否则组件已按旧值编译完毕。
map-merge 为什么没生效，连 .btn-brand 都不生成
根本原因不是函数写错了，而是执行时机不对：$theme-colors 必须在 @import "bootstrap/scss/functions" 之后、@import "bootstrap/scss/variables" 之前合并。Bootstrap 的 _variables.scss 里会直接用 $theme-colors 初始化其他变量（比如 $primary），如果你在它之后才 map-merge，等于改了个寂寞——那些组件样式早已按旧 map 编译完了。
常见错误现象：
- 编译无报错，但
.btn-brand类完全不存在 -
.text-brand能用，.alert-brand却没背景色（因为_alerts.scss依赖$theme-colors生成，而它已加载完毕）
实操建议：
- 确认你的自定义文件（如
_custom-theme.scss）被@import的位置：必须夹在functions和variables之间 - 别用
@use引入 Bootstrap —— 它会破坏变量作用域顺序；坚持用@import（Bootstrap 5 官方仍支持且推荐此方式用于主题定制） - 加一行
@debug $theme-colors;在variables导入前，终端里能看到你新加的键，才算真正“进去了”
想合并嵌套结构，比如按钮不同状态下的颜色，map-merge 不够用
map-merge 是浅合并，遇到嵌套 Map 就停住。比如你想扩展 $theme-colors 里的 "primary"，让它包含 hover 和 disabled 子色值，直接 map-merge($theme-colors, ("primary": ("base": #007bff, "hover": #0056b3))) 没用——它会把整个 "primary" 值替换成新 Map，丢掉原始的 active、focus 等逻辑。
立即学习“前端免费学习笔记（深入）”；
实操建议：
- 用
map-deep-merge（需自行定义，Sass 原生不提供）：封装一个递归函数，逐层判断 key 是否为 map，是则继续 merge，否则覆盖 - 更稳妥的做法是分层控制：不要往
$theme-colors里塞状态，改用独立变量$btn-primary-states: ("hover": #0056b3, "disabled": #6c757d)，然后在_buttons.scss对应位置手动注入 - 如果只是想让
.btn-brand:hover有颜色，别动$theme-colors，直接加一条规则：.btn-brand:hover { background-color: map-get($theme-colors, "brand"); }
map-merge 后某些类还是没出来，比如 .shadow-brand
不是 map-merge 失败，是 Bootstrap 工具类生成机制本身没启用对应模块。.shadow- 类由 utilities/_shadows.scss 控制，而它默认只对 $enable-shadows: true 且 $shadows map 中存在的键生成工具类——但 $shadows 是个独立 map，和 $theme-colors 无关。
实操建议：
- 检查是否启用了阴影工具类：
$enable-shadows: true;必须在variables导入前设置 - 扩展
$shadowsmap：$shadows: map-merge($shadows, ("brand": 0 0.5rem 1rem rgba(map-get($theme-colors, "brand"), .3))); - 确保
@import "bootstrap/scss/utilities/_shadows"没被注释或跳过 -
.shadow-brand不会自动继承$theme-colors里的值，必须显式定义，RGBA 透明度也得自己算好
调试时发现 map-get($theme-colors, "brand") 返回 null
最常见两个原因：键名没加引号，或者变量作用域污染。Sass 把不带引号的 brand 当作变量查找，如果恰好有同名变量（哪怕未定义），结果就是 null 或报错；若在多个 @import 层级中重复声明 $theme-colors，后声明的会覆盖前声明的，导致中间某次 merge 白做了。
实操建议：
- 所有键名强制用双引号：
"brand"，永远别写brand - 避免在多个文件里反复
$theme-colors: map-merge(...)，只在一个入口文件里做一次合并 - 用
@debug分段验证：@debug "before merge:", $theme-colors;、@debug "after merge:", $theme-colors; - 如果用了
@forward或@use with，注意with只转发变量，不执行map-merge逻辑——合并操作必须发生在被@use的模块内部
map-merge 都会变成无效操作。 
