自定义 utility class 前缀必须通过覆盖 sass 变量 $utilities 实现，需用 map-merge 注入含 class、property、values、responsive 等字段的新条目，否则无法生成对应 css；常见失败原因包括未触发编译、入口 import 顺序错误、浏览器缓存及缺失 !important 权重。
自定义 utility class 前缀必须改 Sass 变量，不是改 HTML 或 CSS
Bootstrap 5 的 text-、bg-、px- 这类前缀是硬编码在 Sass 工具类生成逻辑里的，你不能靠重命名 class 或加 wrapper 元素绕过。真正生效的方式只有一种：在编译前覆盖 $utilities map，并确保你的新前缀被正确注入到每个 utility 条目的 class 键中。
常见错误现象：text-brand 能用，但你想改成 color-brand 却完全不输出 —— 因为 $utilities 里仍写的是 "text-brand"，Sass 编译器根本不会去生成 color-brand 对应的 CSS 规则。
- 每个 utility 条目必须显式声明
class键，例如"color-brand": ( class: color-brand, property: color, values: ( brand: #2563eb ) ) - 别漏掉
map-merge($utilities, ...)，直接赋值$utilities: (...)会清空所有默认工具类 - 如果你只改了 HTML 里写的 class 名，没动
$utilities，那编译结果里压根没有这条 CSS，浏览器自然无视
如何让 text-brand 变成 color-brand 并保留响应式断点
目标不是“替换字符串”，而是告诉 Bootstrap 的 utility 生成器：“请把 color-brand 当作一个新工具类，按和 text- 相同的规则生成，包括 color-sm-brand、color-md-brand 等”。关键在 class 和 responsive 两个字段。
示例配置（放在你自己的 custom.scss 入口文件最顶部，在 @import "bootstrap/scss/utilities" 之前）：
$utilities: map-merge(
$utilities,
(
"color-brand": (
class: color-brand,
property: color,
values: ( brand: #2563eb ),
responsive: true,
print: false,
),
)
);
-
class: color-brand决定最终生成的 class 名，不是自动推导的 -
responsive: true才会触发断点循环，生成color-sm-brand等；设为false就只有基础版 - 值推荐用
map-get($theme-colors, primary)替代硬编码色值，避免后期维护脱节
为什么改了 $utilities 还没生成对应 CSS？三个高频卡点
你写了正确的 map，也用了 map-merge，但编译后 CSS 文件里还是找不到 color-brand —— 大概率困在这三处：
- 没运行编译命令：
npm run css或npm run dist；仅保存 Sass 文件不会触发构建 - 入口文件没正确 import 变量：确认你自己的
main.scss里是@import "variables"; @import "utilities";，而不是跳过了variables直接 importbootstrap.scss - 浏览器缓存旧 CSS：DevTools 开着时按
Cmd+Shift+R（macOS）或Ctrl+F5（Windows）强制刷新，或关掉 “Disable cache” 选项
注意：如果你用的是 npm install bootstrap 安装的包，默认不含 SCSS 源码和构建脚本，必须 git clone https://github.com/twbs/bootstrap.git 并 npm install 才能跑 npm run css。
!important 是默认行为，但你的自定义类不带它就容易失效
Bootstrap 5 默认给所有 utility class 加了 !important，这是为了压过组件内联样式或第三方库的规则。但你新增的 color-brand 默认不带，所以常出现“写了 class 没效果”的情况 —— 实际是被 .btn .text 这类更具体的选择器覆盖了。
- 方案一（推荐）：在 utility map 里加
rules: "color !important"，只对这个属性生效 - 方案二：全局关闭，提前设
$enable-important-utilities: false，然后统一用 specificity 控制优先级 - 别手动在 CSS 里写
.color-brand { color: #2563eb !important; }—— 这样就脱离了 utility 系统，无法响应断点、print 等开关
真正麻烦的不是写法，而是忘记 !important 的存在；很多开发者调半天才发现是权重问题，而不是变量没生效。
