Bootstrap 5通过Utility API添加自定义工具类不生效问题求助

自定义工具类不生效是两个核心错误导致的：

• 导入顺序错误：scss/utilities/api 是遍历$utilities映射表、生成最终工具类CSS的逻辑文件，你先导入了该文件（工具类已经生成完成），之后才修改$utilities配置，修改内容不会被已执行的生成逻辑读取。
• 重复导入：你前面已经手动拆分引入了所有Bootstrap子模块，最后又引入了完整的bootstrap.scss，不仅会导致样式重复编译，还会用Bootstrap默认配置覆盖你自定义的映射合并逻辑。
• 自定义$utilities的合并逻辑，必须放在引入Bootstrap核心utilities文件之后、引入utilities/api文件之前，才能被生成逻辑正确识别。

调整导入顺序，删除末尾重复的全量Bootstrap导入，正确代码结构如下：

// 1. 最先导入Bootstrap基础依赖，提供函数、变量、映射、混入能力
@import "../../../bootstrap-5/scss/functions";
@import "../../../bootstrap-5/scss/variables";
@import "../../../bootstrap-5/scss/maps";
@import "../../../bootstrap-5/scss/mixins";
@import "../../../bootstrap-5/scss/utilities";

// 2. 此处为自定义工具类配置的唯一正确位置
$utilities: map-merge(
    $utilities,
    (
        "c-mr": (
            property: margin-right,
            class: c-mr, // 可选，显式指定生成的类名，避免自动生成异常
            values: (
                0: 0rem,
                1: 0.25rem,
                2: 0.5rem,
                3: 1rem,
                4: 1.5rem,
                5: 3rem,
            ),
        ),
    )
);

// 3. 导入布局与组件模块
@import "../../../bootstrap-5/scss/root";
@import "../../../bootstrap-5/scss/reboot";
@import "../../../bootstrap-5/scss/type";
@import "../../../bootstrap-5/scss/images";
@import "../../../bootstrap-5/scss/containers";
@import "../../../bootstrap-5/scss/grid";
@import "../../../bootstrap-5/scss/tables";
@import "../../../bootstrap-5/scss/forms";
@import "../../../bootstrap-5/scss/buttons";
@import "../../../bootstrap-5/scss/transitions";
@import "../../../bootstrap-5/scss/dropdown";
@import "../../../bootstrap-5/scss/button-group";
@import "../../../bootstrap-5/scss/nav";
@import "../../../bootstrap-5/scss/navbar";
@import "../../../bootstrap-5/scss/card";
@import "../../../bootstrap-5/scss/accordion";
@import "../../../bootstrap-5/scss/breadcrumb";
@import "../../../bootstrap-5/scss/pagination";
@import "../../../bootstrap-5/scss/badge";
@import "../../../bootstrap-5/scss/alert";
@import "../../../bootstrap-5/scss/progress";
@import "../../../bootstrap-5/scss/list-group";
@import "../../../bootstrap-5/scss/close";
@import "../../../bootstrap-5/scss/toasts";
@import "../../../bootstrap-5/scss/modal";
@import "../../../bootstrap-5/scss/tooltip";
@import "../../../bootstrap-5/scss/popover";
@import "../../../bootstrap-5/scss/carousel";
@import "../../../bootstrap-5/scss/spinners";
@import "../../../bootstrap-5/scss/offcanvas";
@import "../../../bootstrap-5/scss/placeholders";

// 4. 导入辅助类
@import "../../../bootstrap-5/scss/helpers";

// 5. 最后导入工具类生成API，此时会读取修改后的$utilities生成所有工具类（包含自定义的c-mr）
@import "../../../bootstrap-5/scss/utilities/api";

// 必须删除原文件末尾的 @import "../../../bootstrap-5/scss/bootstrap"; 避免重复导入覆盖配置

调整顺序后仍不生效的话，逐一检查以下项：

• 清理SCSS编译缓存，执行全量重编译，部分构建工具的增量编译会跳过map修改的检测
• 确认自定义工具类的key未和内置工具类重名，当前使用的c-mr符合要求
• 如果需要生成响应式变体，可在自定义配置中添加responsive: true，即可生成对应断点下的工具类
• 可在map合并代码后添加@error map-get($utilities, "c-mr");，如果编译时能打印出你写的c-mr配置，说明map合并逻辑本身没有语法错误

内容的提问来源于stack exchange，提问作者Ryan.Jones