Bootstrap 5 配色必须通过 Sass 变量重写实现，需在入口 SCSS 中于导入 Bootstrap 前重定义 $primary 等基础色、$theme-colors map 及衍生变量（如 $primary-rgb），并用 map-merge 安全扩展颜色；CSS 变量仅局部生效，无法替代编译时定制。
Bootstrap 5 的配色定制不靠配置文件，靠 Sass 变量重写
Bootstrap 5 官方没有提供类似 bootstrap.config.json 或 YAML 配置文件来定义主题色——它压根不读这类运行时配置。所有颜色体系由 Sass 变量驱动，必须在编译前修改源变量值，再重新构建 CSS。
常见错误是试图在 HTML 中引入一个“配色配置 JS 文件”，或以为改 data-bs-theme 就能批量换主色；其实那只是浅层的深色模式开关，和自定义 palette 无关。
- 真正生效的位置：你的项目中
_custom.scss（或入口main.scss）里，在@import "bootstrap/scss/functions"之后、@import "bootstrap/scss/bootstrap"之前重定义变量 - 必须重写的变量包括：
$primary、$secondary、$success等基础色，以及$theme-colors这个 map（用于扩展如indigo、teal等额外色） - 别漏掉衍生变量：
$primary-rgb、$primary-text-emphasis、$primary-bg-subtle—— Bootstrap 5.3+ 大量依赖这些生成文本/背景对比色，不一并更新会导致按钮文字看不清、alert 背景发灰等隐性问题
如何安全扩展 $theme-colors 而不破坏原有工具类
直接覆盖 $theme-colors 整个 map 会丢掉 Bootstrap 默认的 6 种颜色（primary → light），正确做法是用 Sass 的 map-merge() 增量添加：
$theme-colors: map-merge(
$theme-colors,
(
"indigo": #4b0082,
"amber": #ffc107,
"cyan": #00bcd4
)
);
这样编译后，你就能用 text-indigo、bg-amber、btn-cyan 等类名，且原有 btn-primary、text-success 全部保留。
- 注意键名必须是字符串（带引号），否则 Sass 报错：
"indigo"✅，indigo❌ - 值必须是合法颜色值：十六进制、rgb()、color-mix() 均可，但别用变量未定义的颜色名（如
rebeccapurple在部分旧浏览器不支持） - 如果想让新颜色也参与
bg-gradient或border-工具类，无需额外操作——Bootstrap 的循环逻辑已自动遍历整个$theme-colorsmap
为什么改了变量，.btn-outline-* 边框还是灰色？
因为 $theme-colors 只控制实色类（btn-primary）和轮廓类（btn-outline-primary）的主体色，但边框/文字色实际由 $theme-color-contrast-dark 和 $theme-color-contrast-light 决定——它们是硬编码的黑白阈值，不随你新加的颜色自动适配。
- 解决方法：为每个新增颜色手动补充对比色变量，例如：
$indigo-contrast: #fff、$amber-contrast: #000，然后在$theme-colors后加一行：$theme-color-contrast-dark: map-merge($theme-color-contrast-dark, ("indigo": $indigo-contrast)) - 更省事的替代：直接用
color-contrast()函数动态计算，但需确保你的 Sass 版本 ≥ 1.50（Dart Sass），且避免在循环中频繁调用影响编译速度 - 典型翻车场景：给深色
#1a1a2e设了$theme-color-contrast-light: #fff，结果按钮文字在浅色背景上不可见——本质是没区分「深色背景上的文字色」和「浅色背景上的文字色」，得同时配$theme-color-contrast-dark和$theme-color-contrast-light
不编译 Sass 怎么临时换色？CSS 自定义属性方案的边界在哪
Bootstrap 5.2+ 提供了有限的 CSS 变量支持，比如 --bs-primary，但它只影响极少数组件（如 .btn 的 background-color），不触发 .text-primary、.bg-primary 等工具类的实时响应——这些类名仍绑定原始编译出的 CSS 规则。
- 能动的：用
style="--bs-primary: #7c3aed"可即时改变按钮底色，但同页面的<div class="text-primary">文字</div>依然用编译时的#0d6efd - 不能动的：所有依赖
$primary衍生出的阴影、渐变、禁用态透明度（rgba($primary, .15)）都固化在 CSS 里，JS 改变量毫无作用 - 真实可用场景：仅适合单页内局部、少量、不涉及状态变化的配色微调（比如切换品牌色 banner），别指望靠它实现整站主题切换
真要 runtime 换肤，得自己写 JS 扫描并替换所有含 primary 的 class 名，或者用 CSS-in-JS 库接管样式生成——Bootstrap 的 CSS 变量只是个安慰剂接口，别把它当主题引擎用。
