修改 $theme-colors 会影响所有调用 theme-color() 函数的组件（如 .btn-primary、.alert-success），但不影响使用独立变量（如 $gray-200）的组件；须在导入 Bootstrap 前用 map-merge() 安全覆盖，键名需加引号，且自定义样式需显式调用 theme-color() 才能响应。
修改 $theme-colors 会影响哪些组件
直接改 $theme-colors 这个 sass map，是 bootstrap 5+ 中批量控制按钮、表单状态、警告框、徽章等颜色最常用的方式。它不是“只改按钮”，而是所有用 theme-color() 函数取色的地方都会响应——比如 .btn-primary、.alert-success、.badge-info 的背景色，甚至 .form-check-input:checked 的边框色。
但注意：部分组件（如 .card 边框、.table-hover 行背景）默认不走这个 map，它们用的是 $gray-200 或 $gray-100 这类独立变量，改 $theme-colors 对它们没影响。
- 必须在导入 Bootstrap 源文件前定义或覆盖
$theme-colors，否则无效 - 新增的 key（如
purple: #8a6de9）会自动产出.btn-purple、.text-purple等工具类 - 删掉某个 key（如去掉
danger），对应工具类和组件样式会彻底消失，编译时不会报错但可能引发 UI 断裂
map-merge() 覆盖比直接重赋值更安全
别直接写 $theme-colors: (primary: #0d6efd, success: #198754); —— 这会丢掉 Bootstrap 原本定义的所有其他主题色（如 warning、info），导致依赖它们的组件（如 .alert-warning）样式失效。
正确做法是用 map-merge() 只覆盖想改的部分，保留其余：
$theme-colors: map-merge(
$theme-colors,
(
"primary": #4a5568,
"success": #38a169
)
);
- 键名必须加引号（
"primary"），Sass 严格区分带引号字符串和无引号标识符 - 确保
map-merge()在@import "bootstrap/scss/functions";之后、@import "bootstrap/scss/variables";之前执行 - 如果用了
!default声明的变量（如$enable-negative-margins: false !default;），不能靠map-merge()修改，得单独重设
自定义组件样式也想批量响应主题色？得手动接入 theme-color()
你写了自定义卡片 .card-highlight，希望它的边框色随 $theme-colors 里的 primary 动态变？Bootstrap 不会自动帮你绑定——你得显式调用函数：
.card-highlight {
border-left: 4px solid theme-color("primary");
}
否则它永远是写死的颜色。类似地，如果你扩展了 $theme-colors 加了 "brand"，又想让新按钮 .btn-brand 生效，除了在 map 里加项，还得确保 Bootstrap 的按钮循环逻辑（bootstrap/scss/components/_buttons.scss 里的 @each）能读到它——通常只要 map 合并时机对，它就会被纳入。
-
theme-color("xxx")返回的是纯色值（如#0d6efd），不带透明度；需要半透效果得自己套rgba()或用color-contrast() - 如果组件用到了
color-contrast()（比如按钮文字色），它会根据你设的背景色自动选白或黑文字——但前提是背景色确实在$theme-colors里有定义
编译后发现某些颜色没更新？先查 !default 和加载顺序
常见现象：改了 $theme-colors，.btn-primary 颜色变了，但 .navbar-brand 还是蓝色。这不是 map 失效，而是 .navbar-brand 的颜色来自 $link-color，而它默认值是 $blue，且声明为 !default —— 它根本没读 $theme-colors。
这类问题本质是变量层级混乱。排查重点只有两个：
- 打开
node_modules/bootstrap/scss/_variables.scss，搜你要改的样式属性（如navbar-brand），看它最终依赖哪个变量（比如$navbar-brand-color），再顺藤摸瓜找它的默认值来源 - 确认你的自定义变量文件（如
_custom.scss）是否在@import "bootstrap/scss/variables";之前引入；顺序反了，!default就不会被覆盖 - 用
npm run build后检查生成的 CSS，搜索navbar-brand，看实际生效的 color 值是多少，再反推是哪个变量没被覆盖到
真正麻烦的从来不是改 map，而是搞清哪一层变量在控制哪一块像素——尤其当你混用了 Bootstrap 官方构建、CDN、以及第三方主题包的时候。
