必须在自定义Sass入口中按顺序导入functions、variables，用map-merge扩展$utilities后导入utilities；新增项需严格遵循property→responsive→state→value四层结构，补全null及响应式断点，并避免class前缀与内置utility冲突。
Bootstrap 5 的 $utilities Sass map 是唯一入口
想加一个 .text-uppercase-soft 或 .bg-gradient-horiz？不能靠写独立 CSS 文件覆盖，必须修改 Bootstrap 的 $utilities——这是它 Utility API 的核心数据结构，所有 text-*、p-*, m-* 类都从这里生成。直接在 _utilities.scss 里追加条目无效，因为官方构建流程只读取你传给 utility-generator 的那个 map。
实操上，你需要在自定义 Sass 入口（比如 custom.scss）中：先 @import "bootstrap/scss/functions" 和 "bootstrap/scss/variables"，再用 map-merge 扩展 $utilities，最后 @import "bootstrap/scss/utilities"。顺序错一步，新类就不会编译出来。
新增 utility 必须严格匹配 map 结构
每个 utility 条目是四层嵌套 map：property → responsive → state → value。漏掉 responsive（比如没写 sm 或 null），该类就不会响应式；漏掉 state（如 hover），伪类就失效；value 不是字符串或 map，Sass 编译直接报错 Invalid CSS after "...": expected "{", was ";"。
常见错误示例：
// ❌ 错误：缺 responsive 层，.shadow-heavy 永远不生成
$utilities: map-merge($utilities, (
"shadow-heavy": (
property: box-shadow,
values: (heavy: 0 12px 24px rgba(0,0,0,.2))
)
));
<p>// ✅ 正确：补全 null（默认断点）和 hover 等可选状态
$utilities: map-merge($utilities, (
"shadow-heavy": (
property: box-shadow,
class: shadow,
values: (
null: 0 12px 24px rgba(0,0,0,.2),
hover: 0 16px 32px rgba(0,0,0,.25)
)
)
));class 名冲突和覆盖逻辑很隐蔽
Bootstrap 默认的 text-* 已经占用了 text 这个 class 前缀。如果你新增一个 "text-blur": (property: backdrop-filter, ...)，最终生成的类名会是 .text-blur——但它和 .text-primary 共享 text- 前缀，CSS 优先级完全取决于源码顺序，不是你后写的就一定生效。
更危险的是：如果新 utility 的 property 和已有 utility 冲突（比如两个都设 property: color），后者会完全覆盖前者，且无任何警告。建议：
- 用独特前缀，如
blur-、bgx-，避免和text-、bg-碰撞 - 检查
bootstrap/scss/_variables.scss里的$theme-colors和$utilities原始定义，确认 key 名未被占用 - 运行
npx sass --watch src/custom.scss:dist/css/custom.css后，打开生成的 CSS 搜索你的新 class 名，确认是否真的存在
响应式断点必须显式继承或重定义
Bootstrap 5 的 $grid-breakpoints 定义了 xs/sm/md/lg/xl/xxl，但 $utilities 默认只对 sm 及以上生成媒体查询。如果你希望 .pad-vert-xs 在 xs 断点也生效，不能只写 xs: 1rem，还必须把 null（即无断点的基础版）也带上，否则 xs 版本会覆盖基础版，导致桌面端反而没 padding。
正确写法要分两步：
$utilities: map-merge($utilities, (
"pad-vert": (
property: padding-block,
class: pad-vert,
values: (
null: 0.5rem, // 基础值（<sm）
xs: 0.5rem, // xs 断点（≥320px）
sm: 1rem, // sm 断点（≥576px）
md: 1.5rem // md 断点（≥768px）
)
)
));真正容易被忽略的是：Sass 编译时不会校验你写的断点名是否真实存在于 $grid-breakpoints。填个 xxx: 12px，它就默默忽略，既不报错也不生成对应类——得靠人工核对或 grep 输出 CSS 验证。
