升级Sass与sass-loader后React TS项目出现Undefined mixin构建错误

问题核心 #

升级sass: 1.82.0和sass-loader: 16.0.4后，使用Sass模块语法@use替代@import时，Bootstrap内部抛出Undefined mixin错误，指向_assert-ascending($grid-breakpoints, "$grid-breakpoints")。这是因为Bootstrap 5的Sass模块系统要求变量覆盖必须通过@use ... with语句传递，而非单独导入变量文件，否则Bootstrap内部函数无法读取自定义变量。

解决方案 #

1. 调整SCSS变量覆盖方式 #

修改app.scss中Bootstrap的导入逻辑，通过@use ... with在导入Bootstrap核心时直接传递自定义变量，确保变量作用域与Bootstrap内部函数关联：

// 先导入自定义变量文件
@use './scss/abstracts/variables' as custom-vars;
// 导入Bootstrap核心并覆盖指定变量
@use 'bootstrap/scss/bootstrap' with (
  $grid-breakpoints: custom-vars.$grid-breakpoints
);

// 保留其他自定义模块导入
@use './scss/' as *;
@use 'scss/color-themes';

body {
  @include color-themes.themed() {
    background-color: fromTheme(main-background-page-color);
  }
  margin: 0;
}

// 剩余自定义mixin和样式代码保持不变...

2. 修正Webpack与Sass路径解析 #

新版sass-loader无需~前缀即可直接解析node_modules中的模块，确保移除SCSS导入路径中的~，同时检查webpack配置的sass-loader选项：

module: {
  rules: [
    {
      test: /\.(sa|sc|c)ss$/,
      use: [
        'style-loader',
        {
          loader: 'css-loader',
          options: { url: false },
        },
        'postcss-loader',
        {
          loader: 'sass-loader',
          options: {
            implementation: require('sass'),
            sassOptions: {
              api: 'modern-compiler',
              // 可选：添加node_modules到模块解析路径
              includePaths: ['./node_modules']
            },
          },
        },
      ],
    },
  ],
},

关键说明 #

• Bootstrap 5的Sass模块采用隔离作用域，单独导入变量文件无法让Bootstrap内部函数（如_assert-ascending）读取到自定义变量，必须通过@use ... with传递。
• 如果需要覆盖多个Bootstrap变量，可在with语句中添加更多键值对，例如：

  @use 'bootstrap/scss/bootstrap' with (
    $grid-breakpoints: custom-vars.$grid-breakpoints,
    $primary: custom-vars.$custom-primary-color
  );
  

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