必须修改 $utilities 并重新编译 sass 才能生成 text-brand 类，因其由 sass map 驱动生成而非预设列表；漏掉 property/values/responsive 键、顺序错误或未清缓存均导致静默失效。
必须修改 $utilities 并重新编译 Sass，否则 HTML 中写 text-brand 也不会生成对应 CSS 规则——它不是“写了就能用”的预设列表，而是由 Sass map 驱动生成的。
为什么自定义 utility 类不生效
常见错误现象：浏览器开发者工具里搜不到 .text-brand，或编译后的 CSS 文件中完全缺失该类。根本原因不是 class 拼错，而是 $utilities 没被正确扩展，Sass 编译器压根没收到“生成这个类”的指令。
- 直接在 HTML 写
class="text-brand"≠ 告诉 Sass “请输出它” - 漏掉
property、values或responsive键会导致静默失败（无报错，但无输出） - 在
@import "bootstrap/scss/utilities"之后才修改$utilities，等于对已编译完的产物再操作，无效 - 改了
custom.scss却没清缓存、没重新编译，刷新页面也白搭
如何正确定义一个 text-brand 类
关键不是写 CSS，是往 $utilities 里塞结构完整的嵌套 map。以下是你主 Sass 入口（如 custom.scss）顶部应写的最小有效代码：
$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、text-md-brand等断点变体 - 推荐用
brand: map-get($theme-colors, primary)替代硬编码，便于后续主题统一维护 - 必须确保这段代码出现在
@import "bootstrap/scss/functions"和@import "bootstrap/scss/variables"之后、@import "bootstrap/scss/utilities"之前
为什么 class 生效了却压不过按钮文字颜色
现象：text-brand 在普通段落中起作用，但在 <button class="btn"></button> 里失效。这不是类没生成，而是 CSS 权重不够——Bootstrap 默认所有 utility class 都带 !important，而你的自定义项默认不带。
- 修复方式一（推荐）：在 utility map 中加
rules: "color !important"，只对该属性生效 - 修复方式二：全局关掉 utility 的
!important，即在map-merge()前设$enable-important-utilities: false，再手动为关键类加更具体的选择器（如.btn .text-brand） - 别在 HTML 里写
style="color: #2563eb !important"，那绕过了工具类体系，失去响应式和可维护性
class 名冲突和覆盖逻辑很隐蔽
Bootstrap 已占用 text- 前缀（如 text-primary）。你新增 "text-brand"，最终生成的类名是 .text-brand，但它和内置类共享前缀，CSS 优先级完全取决于源码顺序，不是后写的就一定生效。
- 更危险的是 property 冲突：如果两个 utility 都设
property: color，后者会完全覆盖前者，且 Sass 编译不报任何警告 - 避免前缀重叠：想加背景模糊效果，别用
"backdrop-blur"（可能和未来 Bootstrap 版本冲突），考虑"bg-frosted"这类语义清晰、非标准前缀 - 新增项必须严格遵循四层结构：
property → responsive → state → value；漏掉hover就没有伪类，漏掉null就没有默认断点版本
最易被忽略的点是：你写的每一条 map 条目，都必须补全 null 断点（即基础版）、显式声明 responsive 开关、并确认 @include theme-colors() 或 utilities/api 已被引入——否则连 .text-brand 这样的基础类都不会生成。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
