必须在@import前重定义$primary并同步补全衍生变量，否则文字看不清、深色模式对比度崩；错误顺序（先import后赋值）导致变量无效，正确顺序是先声明$primary，再依次导入functions、variables和bootstrap。
直接改 $primary 变量就能换主题色，但必须在 bootstrap sass 模块加载前完成，且要同步补全 $primary-rgb、$primary-text-emphasis 等衍生变量，否则部分组件文字看不清、背景发灰、深色模式下对比度崩掉。
为什么改了 $primary 却还是蓝色？
根本不是代码写错了，而是变量声明顺序不对。Bootstrap 的 $primary 带 !default，只在首次声明时生效；一旦 bootstrap/scss/variables 被加载，后续赋值就完全被忽略。
- ❌ 错误写法：
@import "bootstrap/scss/variables";后再写$primary: #2563eb;→ 不生效 - ✅ 正确顺序：先定义
$primary: #2563eb;，再依次@import "bootstrap/scss/functions";、@import "bootstrap/scss/variables";、@import "bootstrap/scss/bootstrap"; - 别把变量塞进
node_modules/bootstrap/scss/_variables.scss里——下次yarn upgrade就丢 - 用 Webpack/Vite 时慎用
additionalData注入变量，它可能和你手动写的冲突
新增主题色（如 brand）怎么加才不崩默认类？
不能直接重写 $theme-colors，否则 .btn-primary、.alert-success 全部失效。必须用 map-merge() 增量添加，且键名必须加引号。
- ✅ 正确写法：
$theme-colors: map-merge($theme-colors, ("brand": #059669)); - ⚠️ 键名不加引号（如
brand）→ 编译报错Invalid CSS after "": expected "{", was ";" - 必须显式调用
@include theme-colors();（来自bootstrap/scss/utilities/_api.scss），否则不会生成.text-brand、.bg-brand这类工具类 - 确保已导入
bootstrap/scss/utilities或至少bootstrap/scss/utilities/api，否则@include报 “mixin not found”
为什么 --bs-primary 改了，.text-primary 却没变？
CSS 自定义属性和 Sass 工具类是两套独立机制。--bs-primary 只影响明确使用它的组件（如 .btn 的背景），但 .text-primary 是 Sass 编译时从 $theme-colors 生成的静态类，不读 CSS 变量。
- 仅声明
--bs-brand: #0f766e→ JS 可读取，但 HTML 类无效 - 仅在 Sass 中定义
"brand": #0f766e但没调用@include theme-colors()→ 编译后无任何.text-brand类 - 运行时切换主题时，必须一并设置
--bs-brand-rgb、--bs-brand-text-emphasis，否则rgba(var(--bs-brand-rgb), .1)会失效 - 局部切换推荐加作用域：
.my-theme { --bs-primary: #059669; }，避免污染:root
最容易被忽略的是：改完 $primary 后，所有依赖它的组件（Alert、Progress、Toast border、Form-range track）都会跟着变，但它们的对比度逻辑不会自动适配新色值——尤其是浅色文字落在深色背景上时，WCAG AA 很容易不达标。
