必须在@import "bootstrap/scss/variables"前重定义$primary等变量，否则无效；正确顺序是：先声明自定义变量，再依次导入functions、variables、bootstrap；还需同步更新$theme-colors、$primary-rgb等衍生变量。
必须重定义 Sass 变量并在 Bootstrap 源码引入前生效，否则改了也白改。 直接在 CSS 里覆盖 .btn-primary 或用 !important 只能局部“看起来”变了，.text-primary、.border-primary、悬停色、深色模式适配全都会断链。
变量必须在 @import "bootstrap/scss/variables" 之前声明
Bootstrap 的 $primary 等变量带 !default，但只在首次声明时生效。一旦 _variables.scss 被加载，后续赋值就无效。
- 错误写法：
@import "bootstrap/scss/bootstrap"; $primary: #2563eb;→ 完全不生效 - 正确顺序：先声明变量，再依次
@import "bootstrap/scss/functions"、@import "bootstrap/scss/variables"、最后@import "bootstrap/scss/bootstrap" - 推荐建一个
custom.scss作为唯一入口，只放变量和 import，避免逻辑混杂 - 变量名大小写敏感：
$Primary或$primary-color不会被识别，Sass 会静默回退到默认值
只改 $primary 不够，$theme-colors 也要同步
$primary 是基础值，但 .text-primary、.bg-primary 这类工具类实际读取的是 $theme-colors 这个 map。默认它包含 ("primary": $primary)，但如果你重写了整个 $theme-colors，就必须显式包含所有保留的颜色键。
- 想加新色（如
navy）：先定义$navy: #0f766e;，再用$theme-colors: map-merge($theme-colors, ("navy": $navy)); - 直接赋值
$theme-colors: ("primary": #2563eb, "navy": #0f766e);→ 会丢掉secondary、success等所有默认色 - 新增颜色后，必须调用
@include theme-colors();（来自bootstrap/scss/utilities/_api.scss），否则不会生成.text-navy等类
编译没生效？先盯住这三件事
常见“改了但还是蓝色”的原因几乎都集中在这几个环节：
- 项目实际加载的是
bootstrap.min.css（CDN 或dist/css下），根本没走 Sass 编译流程 → 必须确认 HTML 中<link>指向的是你构建出的 CSS，且构建入口是你的custom.scss - Webpack/Vite 配置了
additionalData或prependData自动注入变量 → 它可能把你手动写的$primary覆盖或冲突了 - 用了 Node Sass → 已废弃，不支持 Bootstrap 5.3+ 的新函数；运行
npx sass --version确保是 Dart Sass（2026 年起强制要求）
衍生变量别漏，尤其 $primary-rgb 和深色模式
$primary-rgb 不是自动生成的，它必须和 $primary 同步更新，否则像 rgba($primary-rgb, .5) 这类调用会报错或渲染异常。深色模式下，$primary 默认不会自动变深——它只是个静态值。
- 手动补
$primary-rgb: 37, 99, 235;（对应#2563eb），否则依赖它的 mixin（如button-variant()）会出问题 - 若需深色模式响应，得配合
$color-mode-type: "dark"和自定义@media (prefers-color-scheme: dark)规则，Bootstrap 不自动推导暗色值 -
$link-color默认是$blue，不是$primary；要让链接同步变色，得额外加一行$link-color: $primary;
真正容易被忽略的是：变量修改后，所有基于它计算的状态色（$primary-hover、$primary-border）都由内部函数生成，而这些函数对极端色值（比如极亮或极暗的 $primary）可能产出对比度不足或视觉失衡的结果——这时不能硬调 opacity，得查 bootstrap/scss/mixins/_buttons.scss 里的算法逻辑。
