直接改$primary变量是最稳起点，需在@import前定义并补全$primary-rgb等衍生变量；扩展$theme-colors用map-merge更可持续；css变量仅对部分组件生效，需手动补全衍生值。
直接改 $primary 变量是最稳的起点
改 $primary 就能联动按钮、警告、进度条、徽章、边框、文字等所有用到主色的地方，前提是你的项目走 Sass 编译流程（比如用 Webpack/Vite + Dart Sass），且变量重定义写在 @import "bootstrap/scss/bootstrap" 之前。
常见错误是把 $primary: #4a6fa5; 写在引入 Bootstrap 之后，或者写在 CSS 文件里——那根本不会生效。也别漏掉 !default：写成 $primary: #4a6fa5 !default; 更安全，避免被后续重复声明覆盖。
必须同步更新的衍生变量包括：$primary-rgb（用于 rgba 场景）、$primary-text-emphasis（控制深色文字对比度）、$primary-bg-subtle（浅色背景块）。不设这些，.alert-primary 文字可能看不清，.bg-primary-subtle 背景会发灰。
$theme-colors 扩展比硬编码类名更可持续
想加个 .bg-brand 或 .text-teal？别单独写 CSS 类，用 map-merge 扩展 $theme-colors：
$theme-colors: map-merge($theme-colors, ( "brand": #059669, "teal": #14b8a6 ));
这样就能直接用 .bg-brand、.text-teal，而且它们自动适配深色模式逻辑（如果项目已配 color-mode）和响应式文本对比规则。
注意两点：map-merge 必须在 @import "bootstrap/scss/variables" 之后、@import "bootstrap/scss/bootstrap" 之前执行；扩展的键名必须是字符串（带引号），否则编译报错 Invalid CSS after "...": expected "{", was ";"。
CSS 自定义属性（--bs-primary）只对部分组件生效
Bootstrap 5.2+ 开始支持运行时换色，但仅限明确使用了 CSS 变量的组件，比如 .btn（靠 --bs-btn-bg）、.alert（靠 --bs-alert-bg）。很多旧组件或第三方封装仍硬编码 Sass 值，比如某些自定义表单控件或老版本 bootstrap-icons 的颜色，不会响应 --bs-primary 变化。
局部切换推荐加作用域：.my-theme { --bs-primary: #059669; }，再给容器加 my-theme 类，避免污染全局 :root。但要注意：CSS 变量无法推导 --bs-primary-rgb 这类衍生值，得手动补全，否则 rgba(var(--bs-primary-rgb), .1) 会失效。
用 JS 动态注入变量时，别只设 --bs-primary，还得一并写 --bs-primary-rgb、--bs-primary-text-emphasis 等，否则深色模式下文字可能反白失败。
用 !important 覆盖类名是短期止痛，不是主题方案
写 .btn-primary { background-color: #ff6b35 !important; } 看似快，但实际要同步处理：:hover、:active、:disabled、.btn-outline-primary 的边框色、.text-primary 的文字色、.border-primary 的边框色……漏一个，就出现“按钮变橙，文字还是蓝，边框却消失了”的割裂感。
更麻烦的是维护成本：下次升级 Bootstrap，某个组件内部结构微调（比如从 .progress > .progress-bar 改成 .progress .progress-bar），你那些高权重选择器就全失效，排查起来比重写 Sass 还费时间。
真正容易被忽略的一点：CSS 变量和 Sass 变量不是互斥关系，而是协作关系。Sass 编译时生成默认 CSS 变量值，CSS 变量负责运行时覆盖。想长期稳定，就得同时管住编译时源头和运行时入口，不能只盯一头。
