直接加 class 名无效，因 Bootstrap 5 工具类由 Sass 的 $utilities map 动态生成；未在 map 中配置 text-brand，编译器不输出任何 CSS 规则。
能扩展，但必须走 Sass 编译流程；不编译，text-brand 这类自定义类根本不会生成，写了也无效。
为什么直接加 class 名没用
Bootstrap 5 的工具类不是预设的 CSS 文件，而是由 $utilities Sass map 驱动、在构建时动态生成的。你 HTML 里写 text-brand，但 Sass 没配置过这个 key，编译器就完全忽略它——连一行 CSS 都不会输出。
常见错误现象：
- 加了
text-brand，浏览器开发者工具里搜不到对应样式规则 - 用了
map-merge($utilities, (...))，但位置错了（比如写在@import "bootstrap/scss/utilities"之后），结果默认工具类全丢了 - 值写成
brand: #2563eb，但没配property: color，导致生成的是无效类名或空规则
怎么正确添加一个 text-brand 工具类
核心是往 $utilities 里注入结构合规的 map，并确保加载顺序和变量作用域正确。示例（放在你自己的入口 SCSS 文件最顶部）：
$utilities: map-merge(
$utilities,
(
"text-brand": (
property: color,
values: (
brand: #2563eb,
),
responsive: true,
print: false,
rules: "color !important"
)
)
);
关键点：
- 必须用
map-merge()，不能直接赋值$utilities: ()，否则清空全部默认工具类 -
rules: "color !important"是必须加的，否则你的类权重压不过.btn .text这类组件内样式 -
responsive: true才会生成text-sm-brand等断点类；设为false就只出基础版 - 值推荐用
map-get($theme-colors, primary)替代硬编码，避免维护脱节
扩展后的性能与兼容性影响
每加一组工具类，CSS 体积就线性增长。例如新增一整套 bg-brand + 响应式 + 暗色模式变体，可能增加 1.2KB（未压缩）。删减同样有效：禁用 screenreader 组可省约 0.8KB。
兼容性方面无额外风险，但要注意：
- 所有自定义类默认带
!important（需手动加rules字段），否则容易被第三方库覆盖 - 如果项目同时用 CSS-in-JS 库（如 Emotion），要确保其样式插入顺序晚于 Bootstrap CSS，否则权重要重算
- 修改
$utilities后必须清缓存并重编译，Vite/Hardhat 等工具常缓存 Sass 变量，改了也不生效
最容易被忽略的是 rules 字段和 map-merge 的调用时机——90% 的“加了不生效”问题都卡在这两处，而不是语法或颜色值本身。
