改了$primary但.text-primary仍是旧色，是因为.text-primary从$theme-colors映射表取值而非直接读$primary；必须用map-merge将$primary同步注入$theme-colors，且该语句须在@import "bootstrap/scss/maps";之前执行，否则无效。
为什么改了$primary但.text-primary还是旧色
大概率是$theme-colors映射表没同步更新。Bootstrap 的 .text-primary 类不直接读 $primary，而是从 $theme-colors 这个 map 里取 "primary" 键对应的值——如果你只重定义了 $primary 变量，却没把它塞进 $theme-colors，那所有基于 map 生成的工具类（.text-*、.bg-*、.border-*）都会继续用默认值。
- 检查你的自定义 SCSS 文件中是否包含类似
$theme-colors: map-merge($theme-colors, ("primary": $primary));的语句 - 确认这行代码写在
@import "bootstrap/scss/maps";之前，否则$theme-colors还没被声明，map-merge会报错或静默失败 - 别用赋值覆盖：
$theme-colors: ("primary": #0d6efd);会清空secondary、success等全部默认色，导致.btn-secondary失效
升级 Bootstrap 后 $theme-colors 映射结构变了
Bootstrap 5.3+ 把部分颜色逻辑从硬编码转为函数驱动，比如 text-primary 实际用的是 shade-color($primary, 20%)，而非直接 $primary。如果你升级到了 5.3 或更高，但没重定义 $theme-color-interval（控制深色模式下自动变暗/变亮的步长），就会发现深色模式下文字对比度异常，或者 .text-primary 在暗背景下突然不可读。
-
$theme-color-interval默认是20，表示用shade-color($color, 20%)生成文本色；若你设的$primary是极浅或极深色，可能需要调小这个值（如10）来保对比度 - 升级后务必检查
node_modules/bootstrap/scss/_maps.scss中$theme-colors的初始定义方式——新版本可能已把"primary"键的值从$primary改为var(--bs-primary)，意味着你必须同时注入 CSS 自定义属性才生效 - 如果项目仍用 Sass 编译，且没启用
css-vars模式，就别依赖--bs-primary，老老实实走map-merge路线
如何验证 $theme-colors 是否生效
最直接的办法是编译时加一句调试输出，看最终 map 内容：
@debug $theme-colors;
然后在终端构建日志里搜 DEBUG 行。你会看到类似这样的输出：
DEBUG: ("primary": #4a6fa5, "secondary": #6c757d, "success": #198754, ...)
- 如果
"primary"对应的值还是#0d6efd，说明你的重定义被跳过或覆盖了 - 如果压根没输出，说明
@debug所在文件没被编译流程加载，检查入口 SCSS 文件的@import链路是否漏掉了自定义层 - 注意：某些构建工具（如 Vite 的
sass插件）默认禁用@debug，需手动开启verbose选项
容易被忽略的衍生变量依赖
$theme-colors 不只是给工具类用的，它还被 color-contrast()、shade-color() 等函数内部引用。比如你加了个新色 "navy"，但没同步更新 $theme-colors，那 .btn-outline-navy 虽然能生成，但它的边框色可能用错算法——因为 button-outline-variant() mixin 会查 $theme-colors 获取基准值再计算边框。
- 每次新增或修改主题色，除了
map-merge，还要确认是否影响$theme-colors-dark（深色模式专用映射，5.3+ 引入） -
$primary-text-emphasis、$primary-bg-subtle这类衍生变量不会自动重算，它们依赖$primary值，但如果你用的是 CSS 变量方案，就得手动补全--bs-primary-text-emphasis等对应属性 - 第三方组件（如 Bootstrap Icons）不读
$theme-colors，它们的颜色要单独处理，别指望加个"icon-blue"就能让图标变色
