自定义工具类必须通过 Sass 编译才能生效；Bootstrap 5 的 Utilities API 仅在构建阶段运行，需在 @import 前用 map-merge 覆盖 $utilities 并配置 property/values/responsive 等键，否则类不会输出。
自定义工具类必须走 Sass 编译流程
不编译 Sass，$utilities 就是废变量——改了也白改。Bootstrap 5 的 Utilities API 不是运行时 JS 配置，也不是 CSS-in-JS 那套，它只在 Sass 构建阶段起作用。你写的 text-brand 类不会凭空出现在浏览器里，除非它被 generate-utility() 处理过、并随整个 bootstrap.scss 一起编译输出。
常见错误现象：text-brand 写进 HTML 却没效果；DevTools 里搜不到对应 CSS 规则；甚至 text-primary-emphasis 能用，但你的类完全不渲染。
- 必须在
@import "bootstrap/scss/utilities"之前覆盖$utilities，顺序错就等于没写 - 不能直接赋值
$utilities: ()，会清空全部默认工具类；要用map-merge()或map-deep-merge() - 本地开发时，修改
$utilities后需清缓存（如 Webpack 的cache: false或 Dart Sass 的--no-cache） - 如果用的是预编译的
bootstrap-utilities.css，那根本没法扩展——它只是个快照，不是活接口
添加一个 text-brand 类的最小可行配置
目标很具体：让 text-brand 输出 color: #2563eb，且带响应式变体（如 text-sm-brand）。关键不是写 CSS，是填对 $utilities 里的 map 结构。
示例配置（放在你自己的入口 custom.scss 中，且在 import bootstrap 前）：
<pre class="brush:php;toolbar:false;">$utilities: map-merge(
$utilities,
(
"text-brand": (
property: color,
values: (
brand: #2563eb,
),
responsive: true,
print: false,
rules: "color !important", // 不加这行，很可能被组件样式压住
)
)
);
注意几个易漏点：
brand 是 class 后缀名，不是颜色名；<code>values里键决定生成的类名（text-brand），值决定实际 CSS 值-
responsive: true才会生成text-sm-brand等，设为false则只出基础版 -
rules: "color !important"是属性级控制，不是给整个 class 加!important；缺了它，text-brand很可能输给.btn span这类高权重要素 - 推荐用
map-get($theme-colors, primary)替代硬编码色值，避免维护脱节
Utilities API 的真实优势和硬伤
优势很务实：能精确控制输出体积、按需启用/禁用整组工具（比如关掉 screenreader 类可省约 0.8KB 未压缩 CSS）、与主题色系统天然联动。
但硬伤也很明确：
- 零运行时灵活性：改个断点或加个值，必须重新编译，无法像 Tailwind 的 JIT 模式那样按需生成
- 调试成本高：报错不提示哪条
$utilities配置错了，常表现为“某类消失”或“全量工具类失效”，得靠二分法排查 -
!important是双刃剑：默认开启确保压制力，但你的自定义项默认不继承，容易误以为“没生效”，其实是权重不够 - 嵌套 map 易出错：比如
values里混用字符串和 map、漏掉property键、把responsive写成responsive: null（应为false）
别指望它替代 CSS-in-JS 或原子类框架
Utilities API 是 Sass 层的“生成器”，不是运行时工具集。它不提供条件类、动态值插值、或基于 props 的样式组合能力。如果你需要 text-[color] 这种模式，或者想在 React 组件里传参控制间距，这套机制帮不上忙。
真正容易被忽略的一点是：它的价值高度依赖项目构建链路是否稳定。一旦团队里有人绕过 Sass 直接引用 bootstrap.min.css，所有定制就归零；而这类“临时捷径”，恰恰在赶工期时最常出现。
