Utility API 的本质是通过 Sass 编译时动态配置 $utilities 映射规则，调用 generate-utility() 批量生成工具类，而非手动添加静态 CSS；必须在 @import "bootstrap/scss/utilities" 前用 map-merge 增量扩展，且仅 property、values、responsive、rules 等键被识别生效。
Utility API 的本质不是“加类”，而是“配规则”
它不生成静态 CSS，而是在 Sass 编译时，根据 $utilities 这个嵌套 map 的结构，调用 generate-utility() 动态产出整组类。你改的是配方，不是成品——比如加 text-brand，实际生成的可能是 text-brand、text-sm-brand、text-md-brand 甚至带 !important 的变体，全由配置字段（responsive、rules）决定。
手写样式只能写死一条规则；Utility API 一次配置，批量产出，且天然支持响应式、重要性声明、断点继承等维度。
为什么直接写 .text-brand { color: #0d6efd !important; } 不如用 Utility API
手写样式容易漏掉三件事：
- 响应式变体要手动复制粘贴，
@media (min-width: 576px) { .text-sm-brand { ... } }得自己写、自己维护 - 和 Bootstrap 原生工具类权重不一致：默认
text-primary带!important，你手写的没加，就被覆盖 - 无法参与全局步进控制：比如项目统一把
$spacers改成(1: 0.125rem, 2: 0.25rem)，手写mt-2类不会自动跟着变，但 Utility API 配的 spacing 工具类会
更关键的是，手写样式散落在各处，而 Utility API 的配置集中在一处，可复用、可版本化、可被其他开发者一眼看懂逻辑。
$utilities 配置里哪些键真正影响输出
不是所有字段都有效，只有这几个键被 generate-utility() 显式读取：
-
property：必须是合法 CSS 属性名，如color、margin-top、background-image（注意：Bootstrap 5 官方没配后者，但你可以配） -
values：键为 class 后缀（brand → text-brand），值为最终 CSS 值，支持变量引用，如map-get($theme-colors, primary) -
responsive：布尔值，true才生成text-sm-brand等断点类 -
rules：字符串，用于追加声明，常见写法是"color !important"或"background-image: var(--bs-bg-img)"
漏掉 property 或 values，编译后压根不出 CSS；写错 property 名（比如拼成 colour），浏览器直接忽略整条规则。
最容易卡住的编译顺序问题
Utility API 生效的前提，是你在正确时机、用正确方式合并配置。常见失败场景：
- 在
@import "bootstrap/scss/utilities"之后 才写map-merge—— 此时$utilities已被消费，你的修改无效 - 用赋值代替
map-merge：$utilities: ("text-brand": (...))—— 覆盖了全部原生配置，text-primary等也消失了 - 用 CDN 引入
bootstrap.min.css，却幻想在 HTML 里加text-brand就能生效 —— 没有 Sass 编译，就没有新类
真正起作用的路径只有一条：自定义 _utilities.scss → 放在 @import "bootstrap/scss/utilities" 之前 → 用 map-merge 增量扩展 → 重新编译。
