必须重编译 Sass 源码才能真正修改 Bootstrap 5 主题颜色；仅 CSS 覆盖或 CDN 引入的 bootstrap.min.css 无法全局生效，需确认构建流程走 Sass 编译、变量在 @import 前定义、同步设置衍生变量（如 $primary-rgb、$primary-text-emphasis）、扩展 $theme-colors 而非覆盖、用 $primary-hover 等变量统一控制状态色，并区分 .text-primary（静态）与 .text-body-primary（深色模式自适应）。
必须重编译 Sass 源码才能真正修改 Bootstrap 5 的主题颜色，仅靠 CSS 覆盖或 CDN 引入的 bootstrap.min.css 无法全局生效。
改 $primary 变量前先确认构建流程是否走对
很多项目“改了变量但没生效”，根本原因是压根没进 Sass 编译环节。检查你实际加载的 CSS 是否来自自己构建的文件，而不是 CDN 或 dist/css/bootstrap.min.css。如果 HTML 中 <link> 指向的是预编译 CSS，那你在 _custom.scss 里写一百遍 $primary: #2563eb 都不会影响页面。
- 用
npm install bootstrap安装后，确保项目里有node_modules/bootstrap/scss/目录 - 入口 SCSS 文件（如
app.scss）第一行就得是变量重定义，不能在@import "bootstrap/scss/bootstrap"之后 - 构建工具（Vite/Webpack）需配置 Sass 加载器，并正确解析
@import路径；若用了additionalData，可能造成变量被重复注入而覆盖你的定义
$primary 不是唯一要动的变量
只改 $primary 很容易导致文字看不清、背景色错乱或组件状态异常。Bootstrap 会基于它推导出多个衍生变量，这些必须同步设置或允许自动计算：
-
$primary-rgb：必须手动设为对应 RGB 值（如37, 99, 235），否则rgba(var(--bs-primary-rgb), .1)这类用法失效 -
$primary-text-emphasis：控制.text-primary在浅底上的对比度，高饱和主色（如亮橙#ff6b35）默认生成的文本色常太暗，需显式重写 -
$theme-colors：虽然默认 map 已含primary: $primary，但若你新增了brand色，必须用map-merge($theme-colors, ("brand": #2563eb))扩展，不能直接赋值新 map 否则丢掉secondary等默认键
按钮 hover 色不对？别硬写 CSS 覆盖
直接写 .btn-primary:hover { background-color: #xxx } 看似快，实则破坏状态逻辑——禁用态、焦点环、深色模式下都可能不一致。正确做法是让 Sass 自动推导：
- Bootstrap 默认用
darken($primary, 10%)算$primary-hover，但对某些色值（如低明度紫）可能过深 - 可手动重写该变量：
$primary-hover: darken($primary, 5%);，它会影响所有依赖它的组件（.btn-primary:hover、.alert-primary:hover等） - 避免用
!important或内联样式覆盖，这类补丁在升级 Bootstrap 或加新组件时极易断裂
深色模式下 .text-primary 不变亮，这不是 bug
Bootstrap 的 .text-primary 是静态语义色，不响应 data-bs-theme="dark"。它和 .bg-primary 本就不是一对反色，强行搭配小字号文本常不满足 WCAG AA 对比度。
- 真要适配深色模式，应改用
.text-body-primary—— 它背后调用color-contrast()动态计算可读色，在浅/深模式下分别取#212529和#f8f9fa - 若坚持用
.text-primary名称，需在自定义变量中同时定义$primary-dark和$primary-light，再配合[data-bs-theme="dark"]媒体查询手动切，但维护成本陡增 - 最常被忽略的一点：
$primary-bg-subtle和$primary-border-subtle在 5.3+ 中新增，不设它们会导致浅色背景下的 subtle 类（如.bg-primary-subtle）仍用旧值
