因为Bootstrap 5工具类由Sass编译时动态生成，text-brand未在$utilities中配置，故无对应CSS规则；需在@import前用map-merge向$utilities添加property、values、responsive等键的结构化配置并重编译。
为什么直接加 text-brand 类名没效果
因为 Bootstrap 5 的工具类不是“写完就能用”的静态 CSS，而是由 Sass 编译时动态生成的。你 HTML 里写了 text-brand，但 Sass 源码里没配它，编译结果里压根没有这条 CSS 规则——浏览器自然忽略。
常见错误现象：text-primary 能生效，text-brand 写了却完全没颜色变化；检查 DevTools 发现该 class 根本没出现在 Styles 面板里。
- 必须在 Sass 编译流程中修改
$utilities变量，再调用generate-utility() - 不能靠覆盖 CSS 文件、也不能靠 JS 动态注入 class 名
- 若用 CDN 引入
bootstrap.min.css，Utility API 完全不可用——它只存在于 Sass 源码层
怎么正确添加一个 text-brand 工具类
核心是往 $utilities 这个嵌套 map 里塞结构正确的配置项，并确保它在 @import "bootstrap/scss/utilities" 之前被合并。
示例（写在你自己的 _utilities.scss 中）：
$utilities: map-merge(
$utilities,
(
"text-brand": (
property: color,
values: (
brand: map-get($theme-colors, primary),
),
responsive: true,
rules: "color !important",
)
)
);
-
property必须是合法 CSS 属性名，如color、margin、border-radius -
values是键值对，key 成为 class 后缀（brand→text-brand），value 是实际 CSS 值 -
responsive: true才会生成text-sm-brand、text-md-brand等断点类 -
rules: "color !important"补上!important，否则容易被组件样式覆盖（默认工具类都带这个）
删掉不用的工具类能省多少体积
删减确实有效，但收益和风险需权衡。比如禁用整组 screenreader 类可减约 0.8KB（未压缩），而移除全部 float 类约省 0.3KB。
更典型的场景是：项目完全不用 text-decoration 相关类，或已弃用 shadow 体系。
- 用
map-merge($utilities, ("text-decoration": null))可彻底剔除该组 - 别用
$utilities: ()全量重置，会清空所有默认类，包括mt-3、fw-bold这些高频类 - 注意
map-deep-merge才是官方推荐方式，map-merge对深层嵌套支持有限，可能导致响应式变体缺失 - 改完必须清缓存、重编译——Vite/HMR 有时会复用旧的 CSS 模块，导致“明明改了却不生效”
Utility API 的扩展代价在哪
最大的隐性成本不在代码量，而在维护链路变长：每次升级 Bootstrap 版本，都要核对 $utilities 结构是否变更、generate-utility() 是否有参数调整、新引入的工具组（如 v5.3 的 aspect-ratio）是否干扰你的自定义逻辑。
另一个易忽略点：所有自定义 utility 默认不继承 Bootstrap 的响应式断点定义（$grid-breakpoints），如果你改过断点，必须同步在 values 或 responsive 配置里显式声明，否则 text-sm-brand 可能对应错的媒体查询。
最后提醒：!important 是双刃剑。加它解决覆盖问题，但也让调试更难——当你发现某个文字颜色死活调不了，先搜 !important 在哪下的手。
