使用Dart Sass编译Bootstrap 5.0.2时出现报错求助

问题重现 #

尝试通过SCSS自定义Bootstrap主色调，已安装Dart Sass，在custom.scss中添加@import "bootstrap";（已配置绝对路径）时触发报错，错误指向Bootstrap内置的opaque()函数，且报错行随机跳转（删除当前报错行后错误转移到上一行），未修改过Bootstrap原始SCSS文件。报错详情：

150 │   @return mix(rgba($foreground, 1), $background, opacity($foreground) * 100);
    │           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ╵
    path\to\webapp\webroot\bootstrap-5.0.2\scss\_functions.scss 150:11            opaque()
    path\to\webapp\webroot\bootstrap-5.0.2\scss\mixins\_table-variants.scss 4:28  table-variant()
    path\to\webapp\webroot\bootstrap-5.0.2\scss\_tables.scss 134:3                @import
    path\to\webapp\webroot\bootstrap-5.0.2\scss\bootstrap.scss 22:9               @import
    path\to\webapp\webroot\scss\custom.scss 11:9                                  root stylesheet

排查与解决方案 #

• 验证Dart Sass版本兼容性
  Bootstrap 5.0.2要求Dart Sass版本≥1.32.0，过高或过低版本都可能引发函数兼容性问题。执行以下命令检查当前版本：

  sass --version
  

  如果版本不符合，通过npm调整（假设用npm安装）：

  # 安装指定兼容版本
  npm install sass@~1.32.0 --save-dev
  

• 检查自定义变量合法性
  自定义主色调等变量时，必须确保是合法的Sass颜色值，避免传入字符串、数字等非颜色类型。例如：
  ✅ 正确写法：

  $primary: #2563eb; // 十六进制颜色
  $primary: rgb(37, 99, 235); // RGB颜色
  

  ❌ 错误写法：

  $primary: "blue"; // 字符串
  $primary: 2563eb; // 无#前缀的十六进制值
  

  建议先注释所有自定义变量，仅保留@import "bootstrap";测试，若不再报错则逐个恢复变量排查问题项。

• 清理Sass缓存并重新编译
  缓存损坏可能导致无规律的报错，执行以下操作：

  1. 删除项目根目录下的.sass-cache文件夹
  2. 编译时添加--no-cache参数禁用缓存：

     sass scss/custom.scss css/custom.css --no-cache
     

• 确认Bootstrap导入路径正确性
  即使配置了绝对路径，仍需确认路径指向的是Bootstrap的bootstrap.scss主文件，而非单个组件文件。例如根据项目结构调整路径：

  // 假设Bootstrap在webroot/bootstrap-5.0.2/scss下
  @import "../bootstrap-5.0.2/scss/bootstrap";
  

• 重新替换Bootstrap原始文件
  若以上步骤无效，可能是Bootstrap的SCSS文件因下载或存储损坏导致。重新下载Bootstrap 5.0.2的源码包，解压后替换项目中的Bootstrap SCSS文件。

内容的提问来源于stack exchange，提问作者Jack 't Jong