Utilities API 是 Bootstrap 5 提供的 Sass 层级工具类生成机制，通过 $utilities 映射变量与 generate-utility() 混合动态编译 CSS 类，需经 Sass 编译流程定制，不支持纯 CSS 引入扩展。
Utilities API 是什么，它不是 CSS 类列表
Bootstrap 5 的 Utilities API 不是预设好、直接用的类名集合，而是一套 Sass 层面的生成机制——它通过 $utilities 这个嵌套映射变量 + generate-utility() 混合，动态编译出最终的 CSS 工具类。你改的是“配方”，不是“成品”。
这意味着：不碰 Sass，就无法真正扩展或删减工具类；只靠引入 bootstrap-utilities.css 文件，你拿到的只是官方打包好的那一版，没法定制。
- 常见错误现象：
text-uppercase能用，但想加一个text-capitalize-first却找不到对应类——因为这根本不在默认配方里 - 使用场景：需要统一控制所有
spacing类的步进值、为自定义颜色系统批量生成bg-/text-类、彻底移除项目中用不到的float工具类 - 性能影响：增删工具类直接影响最终 CSS 体积；比如禁用整组
screenreader类，可减少约 0.8KB（未压缩）
怎么在项目里真正启用和修改它
必须走 Sass 编译流程，且 @import 顺序不能错——这是最容易卡住的地方。Bootstrap 官方 bootstrap.scss 把 _utilities.scss 放在最后，但你要插自己的定制，就得在它之前塞入自己的 _utilities.scss。
- 关键顺序（缺一不可）：
@import "bootstrap/scss/functions";→ 你的_default-variable-overrides.scss→@import "bootstrap/scss/variables";→ 你的_variable-value-using-variable.scss→ … →@import "bootstrap/scss/utilities";→ 你的_utilities.scss - 你的
_utilities.scss文件里，必须先用map-merge($utilities, ...)扩展$utilities，再调用@include generate-utility(...)，否则不会产出新类 - 参数差异：每组工具类（如
spacing、border-radius）的配置结构不同；比如spacing依赖$spacers变量，而border-radius读的是$border-radius和$border-radius-sm等
为什么直接覆盖 $utilities 变量会失效
因为 Bootstrap 内部不是简单地 $utilities: map-merge($utilities, ...) 一次就完事——它在 utilities/_api.scss 中分多轮合并，还夹杂了 if 判断和 map-deep-merge 逻辑。直接赋值会跳过这些处理，导致部分子配置被忽略。
- 常见错误现象：你在自己的文件里写
$utilities: map-merge($utilities, ("opacity": (...))，结果opacity-25出来了，但响应式变体（如md:opacity-50）没生成 - 正确做法：用 Bootstrap 提供的
map-deep-merge（在functions/_maps.scss里），或更稳妥地，在utilities/_api.scss后再追加一次@include generate-utility(...)单独处理新组 - 兼容性影响：v5.3+ 对
map-deep-merge的实现有小调整，如果你用的是较老的定制模板，升级后可能丢失嵌套层级
别忘了它只管生成，不管 JS 或 HTML 结构
Utilities API 生成的全是纯 CSS 类，它不参与组件逻辑、不绑定事件、也不校验 HTML 语义。比如你用 API 加了 visually-hidden-focusable，但若没配 tabindex，键盘焦点依然会跳过该元素。
- 容易踩的坑：以为加了
sr-only类就满足无障碍要求，实际上它只是视觉隐藏，屏幕阅读器仍可读取；真要“仅对屏幕阅读器可见”，得用visually-hidden+ 配合aria-live等手动控制 - 使用场景限制：API 无法生成带媒体查询嵌套的复杂行为（例如“仅在 hover 时生效的 padding”），那得退回写普通 CSS 规则
- 真实代价：每个新增工具类都会增加 CSS 选择器数量，大量自定义类可能触发浏览器样式计算瓶颈（尤其在低配安卓 WebView 中）
最常被忽略的一点：API 本身不校验类名冲突。你加了个 bg-brand，但如果第三方库也定义了同名类，Sass 编译时不会报错，运行时谁在后面谁赢——得靠你人工盯住 $theme-colors 和外部依赖的命名空间。
