自定义工具类需修改$utilities并重新编译sass，否则html中写text-brand也不会生成对应css；因其非预设列表，而是由sass map驱动生成，漏配property、values、responsive或rules等键将导致静默失败。
自定义 Bootstrap 5 工具类不会自动生效，必须改 $utilities 并重新编译 Sass —— 写 text-brand 到 HTML 里却没颜色，不是 class 拼错了，是 Sass 根本没生成它。
为什么加了 class 却没样式？
Bootstrap 5 的工具类不是“写完就能用”的预设 CSS 列表，而是由 $utilities 这个 Sass map 驱动生成的。你没把它加进这个 map，Sass 编译器就完全忽略它，连一行 CSS 都不会输出。
- 常见错误现象：
text-primary有效，但自己写的text-brand在浏览器里查不到对应 CSS 规则 - 根本原因：直接在 HTML 中写
class="text-brand"≠ 告诉 Sass “请生成这个类” - 关键路径：修改
$utilities→ 重新编译bootstrap.scss→ 输出新 CSS - 别试图用
!important覆盖 —— 类都不存在，覆盖无从谈起
如何正确添加一个 text-brand 工具类？
必须在导入 Bootstrap utilities 前，用 map-merge() 扩展 $utilities，且结构完整。漏掉 property 或 values 就会静默失败。
- 在你自己的主 Sass 入口文件（如
custom.scss）顶部写： $utilities: map-merge( $utilities, ( "text-brand": ( property: color, values: (brand: #2563eb), responsive: true, print: false, ) ) );-
brand是 class 后缀名（生成text-brand），不是变量名；#2563eb是实际值 - 若只要非响应式版本，显式设
responsive: false，否则小屏下可能意外继承该色 - 推荐用
map-get($theme-colors, primary)替代硬编码值，便于主题统一维护
为什么我的 text-brand 没压过按钮内联样式？
Bootstrap 5 默认所有工具类都带 !important，但你的自定义项默认不带 —— 这是最大隐性坑点。
- 现象：
text-brand在普通段落中生效，但在<button class="btn"></button>里失效 - 原因：按钮组件的
.btn .text规则权重更高，而你的类没!important - 修复方式一（推荐）：在 utility map 里加
rules: "color !important"，只对当前属性生效 - 修复方式二：全局关掉 —— 在
map-merge()前设$enable-important-utilities: false，再手动为关键类加!important - 别在 HTML 里写
style="color: #2563eb !important"，那绕过了工具类体系，失去响应式和维护性
编译前必须清理缓存 & 注意加载顺序
改了 $utilities 却没看到效果，90% 是因为 Sass 缓存或导入顺序错位。
-
@import "bootstrap/scss/utilities"必须放在你扩展$utilities的代码之后，否则你的 merge 被覆盖 - 如果你用的是 Vite / Webpack / Dart Sass CLI，务必清掉旧的 CSS 缓存或
.sass-cache目录 - 不要直接修改
node_modules/bootstrap/scss/utilities/_variables.scss—— 下次npm update就被重置 - 验证是否成功：检查编译后 CSS 文件里有没有
.text-brand和.text-sm-brand等规则
最常被跳过的其实是 responsive: true 和 rules: "color !important" 这两个键 —— 它们不报错，但缺一不可；一旦漏掉，你写的 class 就像没写一样安静。
