必须重定义$primary变量并在@import "bootstrap/scss/variables"前重新编译Sass，否则仅CSS覆盖会导致.alert-primary、.bg-primary等样式脱节，且深色模式失效；正确做法是按functions→variables→mixins顺序导入，并用map-merge扩展$theme-colors。
直接覆盖 .btn-primary 会导致样式脱节
你改了 .btn-primary { background-color: #e74c3c !important; }，按钮变红了，但 .alert-primary、.bg-primary、.form-check-input:checked 还是默认蓝色——因为它们各自独立声明，没共享底层逻辑。更关键的是，像 box-shadow: 0 0 0 .25rem rgba(var(--bs-primary-rgb), .5) 这种写法根本不会响应你的 class 覆盖，它读的是 CSS 变量值，不是你硬写的颜色。
常见现象：上线后发现“主题色只在按钮上生效”，其他组件颜色不一致；换深色模式时，手动覆盖的 CSS 完全没反应；后续升级 Bootstrap，所有 !important 规则都得重查是否还匹配新结构。
$primary 必须在 @import "bootstrap/scss/variables" 前定义
顺序错了就白干。Bootstrap 5 的变量依赖链非常严格：functions → variables → mixins → 其他模块，缺一不可。
- 先写
$primary: #6f42c1;，再@import "bootstrap/scss/functions"; - 必须在
@import "bootstrap/scss/variables";之前声明变量，否则会被默认值覆盖 - 漏掉
functions或mixins，很多变量（比如$grid-columns）和 mixin（比如breakpoint-min()）会报错 undefined - 用 Webpack/Vite 时，确保 Sass 加载器配置了
includePaths，否则@import "bootstrap/scss/..."找不到路径
新增配色如 indigo 必须用 map-merge($theme-colors, ("indigo": #4b0082))
只写 $indigo: #4b0082; 没用，bg-indigo 类根本不会生成。Bootstrap 的工具类是编译期生成的，靠 $theme-colors 这个 map 驱动。
立即学习“前端免费学习笔记（深入）”；
实操要点：
- 必须重定义整个
$theme-colorsmap，不能只加一个 key - 推荐写法：
$theme-colors: map-merge($theme-colors, ("indigo": #4b0082)); - 如果删了
"danger"却没同步更新$theme-colors，text-danger、border-danger就会消失 - 所有依赖该 map 的模块（utilities、buttons、alerts）才会真正产出对应 class
修改 $container-max-widths 时必须同步调整 $grid-breakpoints
否则断点类（如 .container-lg）和实际容器宽度不匹配。比如把 xl 断点从 1140px 改成 1200px，但忘了改 $container-max-widths 里的 xl 值，结果 .container-xl 在 1200px 屏幕下还是按 1140px 渲染。
容易被忽略的细节：
-
$grid-breakpoints控制媒体查询阈值，$container-max-widths控制容器最大宽度，二者必须一一对应 - 改了
$grid-breakpoints但没重编译，CSS 里媒体查询还是旧值 - 某些组件（如 navbar 折叠点）也依赖
$grid-breakpoints，改完要全链路验证
