Bootstrap 5自定义Utility类生成失败问题求助

问题现象 #

• 在现有Bootstrap SCSS导入结构末尾添加自定义工具类代码，预期生成.test-25等类，但未成功
• CSS编译无报错，但自定义工具类未出现在最终输出结果中
• 测试Sass代码执行正常（如添加body { background: red; }可生效），但自定义工具类代码被编译后剥离

用户代码 #

// Bootstrap SCSS

// 1. Include functions first (so you can manipulate colors, SVGs, calc, etc)
@import 'bootstrap/scss/functions';

// 2. Include remainder of required Bootstrap stylesheets
@import './variables';

// 3. Include any default variable overrides here
@import '../custom';

// 4. Include any default map overrides here

// 5. Include remainder of required parts
@import 'bootstrap/scss/maps';
@import 'bootstrap/scss/mixins';
@import 'bootstrap/scss/root';

// 5. Custom mixins
@import './mixins/forms';

// 6. Optionally include any other parts as needed
@import 'bootstrap/scss/utilities';
@import './reboot'; // evi
@import 'bootstrap/scss/type';
@import 'bootstrap/scss/images';
@import 'bootstrap/scss/containers';
@import 'bootstrap/scss/grid';
@import 'bootstrap/scss/tables';
@import 'bootstrap/scss/forms/floating-labels';
@import 'bootstrap/scss/forms/form-check';
@import 'bootstrap/scss/forms/form-control';
@import './forms/form-range'; // evi
@import 'bootstrap/scss/forms/form-select';
@import 'bootstrap/scss/forms/form-text';
@import 'bootstrap/scss/forms/input-group';
@import 'bootstrap/scss/forms/labels';
@import 'bootstrap/scss/forms/validation';
@import 'bootstrap/scss/buttons';
@import 'bootstrap/scss/transitions';
@import 'bootstrap/scss/dropdown';
@import 'bootstrap/scss/button-group';
@import 'bootstrap/scss/nav';
@import 'bootstrap/scss/navbar';
@import 'bootstrap/scss/card';
@import 'bootstrap/scss/accordion';
@import 'bootstrap/scss/breadcrumb';
@import 'bootstrap/scss/pagination';
@import 'bootstrap/scss/badge';
@import 'bootstrap/scss/alert';
@import 'bootstrap/scss/progress';
@import 'bootstrap/scss/list-group';
@import 'bootstrap/scss/close';
@import 'bootstrap/scss/toasts';
@import 'bootstrap/scss/modal';
@import 'bootstrap/scss/tooltip';
@import 'bootstrap/scss/popover';
@import 'bootstrap/scss/carousel';
@import 'bootstrap/scss/spinners';
@import 'bootstrap/scss/offcanvas';
@import 'bootstrap/scss/placeholders';
@import 'bootstrap/scss/helpers';

// my code: 

$utilities: map-merge(
    $utilities, (
    "test": (
      property: opacity,
      values: (
        0: 0,
        25:.25,
        50:.5,
        75:.75,
        100: 1,
      )
    )
  )
);

// 7. Optionally include utilities API last to generate classes based on the Sass map in `_utilities.scss`
@import 'bootstrap/scss/utilities/api';

解决方法 #

1. 调整代码顺序（核心修复） #

问题出在自定义工具类代码的位置：当前代码放在所有组件导入之后，可能存在后续组件意外修改$utilities变量的情况。正确的位置是导入bootstrap/scss/utilities之后，其他组件导入之前，确保修改后的$utilities能被最后导入的utilities/api读取并生成类。

修改后的关键代码片段：

// 6. Optionally include any other parts as needed
@import 'bootstrap/scss/utilities';

// 自定义工具类移到此处
$utilities: map-merge(
    $utilities, (
    "test": (
      property: opacity,
      values: (
        0: 0,
        25:.25,
        50:.5,
        75:.75,
        100: 1,
      )
    )
  )
);

// 后续组件导入
@import './reboot'; // evi
@import 'bootstrap/scss/type';
// ... 剩余组件导入代码 ...

// 7. 最后导入工具类API生成代码
@import 'bootstrap/scss/utilities/api';

2. 验证变量修改是否生效 #

在修改$utilities后添加@debug指令，编译时查看日志，确认自定义的test项已加入$utilities映射：

$utilities: map-merge(...);
@debug $utilities; // 编译日志会输出完整的$utilities内容

3. 排查变量覆盖问题 #

检查后续导入的组件文件或自定义文件（如../custom、./variables），确认没有重新定义$utilities变量的代码，避免你的修改被覆盖。

内容的提问来源于stack exchange，提问作者user3531149