$utilities 是 Bootstrap 5 中定义工具类生成规则的 Sass map，需在导入 utilities 前用 map-merge 覆盖；添加 text-brand 需配置 property、values、responsive 等键，并注意加载顺序与缓存清理。
Bootstrap 5 的 $utilities 是什么，不是 CSS 类列表
它是一组 sass map 配置，告诉 bootstrap “该生成哪些工具类、怎么生成”，不是现成的 class 名单。你改了它，build 时才会产出对应 css；光在 html 里写 text-[value] 不会生效。
常见错误现象：text-primary-emphasis 能用，但自己加个 text-brand 就不渲染 —— 因为没进 $utilities map，Sass 编译器根本不知道要造这个类。
-
$utilities默认定义在scss/utilities/_variables.scss，必须在@import "bootstrap/scss/utilities"前覆盖它 - 每个 utility 条目至少含
property、values、class三个 key；responsive和print是可选开关 - 值支持字符串、map、
null（禁用默认）、map-get()引用已有调色板
如何添加一个自定义文字颜色工具类 text-brand
目标：让 text-brand 输出 color: #2563eb，且带响应式断点（text-sm-brand 等）。
关键不是写 CSS，是往 $utilities 里塞结构正确的 map。直接改 Bootstrap 源码不行，得在你自己的 Sass 入口文件里提前声明：
$utilities: map-merge(
$utilities,
(
"text-brand": (
property: color,
values: (
brand: #2563eb,
),
responsive: true,
print: false,
),
)
);
注意：brand 是 class 后缀名（生成 text-brand），#2563eb 是实际值；responsive: true 才会生成 text-sm-brand 等。
- 别漏掉
map-merge()，直接赋值$utilities: (...)会清空所有默认工具类 - 如果只想要非响应式版本，设
responsive: false，否则小屏下可能意外继承颜色 - 值里用变量更安全，比如
brand: map-get($theme-colors, primary)，避免硬编码
!important 开关和冲突处理
默认所有 utility class 都带 !important，这是 Bootstrap 5 的设计选择 —— 确保能压过组件内联样式或第三方 CSS。但你的自定义类默认不带，容易被忽略。
现象：写了 text-brand，结果按钮内部文字还是灰色 —— 因为按钮组件的 .btn .text 规则权重更高，而你的类没 !important。
- 加
rules: "color !important"到 utility map 里（不是整个 class 加，是属性级控制） - 或者统一关掉所有 utility 的
!important：在覆盖$utilities前设$enable-important-utilities: false - 关掉后务必检查组件是否依赖它，比如
visually-hidden在某些屏幕阅读器场景下失效风险上升
为什么改完 Sass 重新编译，HTML 里还是没效果
最常卡在这一步：配置写了，npm run build 也过了，但浏览器里查不到新 class 的 CSS 规则。
核心原因只有两个：加载顺序错、缓存没清。
- Sass 文件必须按顺序导入：
your-variables.scss→bootstrap/scss/functions→bootstrap/scss/variables→bootstrap/scss/utilities，中间插任何@import "bootstrap/scss/utilities"都会导致你的map-merge失效 - Vite/Webpack 的 CSS 缓存极顽固，改完 Sass 后强制删
node_modules/.vite或.cache目录再启动 - 检查浏览器开发者工具里，新生成的 CSS 是否真在
<style>标签中，还是被其他 CSS 覆盖（看 computed 样式里 color 值来源）
真正麻烦的从来不是语法，是 Sass 加载链里某一行 import 的位置偏了 1 行，或者热更新把旧 CSS 残留在内存里没刷掉。
