BigCommerce Stencil中单个SASS文件math.div无效CSS错误修复咨询

问题背景 #

搭建BigCommerce Stencil环境时，更新依赖并运行sass-migrator division修复了大部分文件的除法语法问题，但node_modules/@bigcommerce/citadel/dist/tools/toolkit.scss仍报错，错误提示无法识别math.div语法：

Invalid CSS after "...   @return math": expected expression (e.g. 1px, bold), was ".div($num, ($num * "
        on line 29 of ../../node_modules/@bigcommerce/citadel/dist/tools/toolkit.scss
        from line 13 of stdin
>>     @return math.div($num, ($num * 0 + 1));

涉及代码片段：

// Rem Calculations
// -----------------------------------------------------------------------------

@function stripUnit($num) {
    @return math.div($num, ($num * 0 + 1));
}

// scss-lint:disable ZeroUnit
@function convertToRem($value, $base-value: $fontSize-base) {
    $value: math.div(stripUnit($value), stripUnit($base-value)) * 1rem;
    @if ($value == 0rem) { $value: 0; } // Turn 0rem into 0
    @return $value;
}

报错原因 #

1. 缺少math模块引入：文件未声明@use 'sass:math';，导致Sass无法识别math命名空间
2. Sass版本过低：math.div是Sass 1.33.0+才支持的语法，若项目Sass版本低于此则会报错
3. sass-migrator未处理node_modules文件：默认情况下，sass-migrator不会扫描node_modules目录，因此该文件未被迁移

修复方案 #

方案1：手动修改文件（临时解决） #

直接编辑node_modules/@bigcommerce/citadel/dist/tools/toolkit.scss：

• 若你的Sass版本≥1.33.0，在文件顶部添加：

  @use 'sass:math';
  

• 若使用低版本Sass，将所有math.div(a, b)替换为除法运算符写法（用括号避免歧义）：

  @function stripUnit($num) {
      @return $num / ($num * 0 + 1);
  }
  
  @function convertToRem($value, $base-value: $fontSize-base) {
      $value: (stripUnit($value) / stripUnit($base-value)) * 1rem;
      @if ($value == 0rem) { $value: 0; }
      @return $value;
  }
  

注意：手动修改node_modules文件会在npm install后被覆盖，仅适合临时测试

方案2：用patch-package持久化补丁（推荐） #

1. 安装patch-package：

   npm install patch-package --save-dev
   

2. 按方案1修改node_modules/@bigcommerce/citadel/dist/tools/toolkit.scss中的代码
3. 生成补丁文件：

   npx patch-package @bigcommerce/citadel
   

4. 在package.json的scripts中添加自动应用补丁的命令：

   "scripts": {
       // 其他脚本...
       "postinstall": "patch-package"
   }
   

后续执行npm install时，补丁会自动应用到citadel包中。

方案3：升级Sass版本 #

检查当前Sass版本：

npm list sass

若版本低于1.33.0，升级到最新稳定版：

npm install sass@latest --save-dev

升级后确保文件顶部引入sass:math模块即可。

方案4：让sass-migrator处理该文件 #

直接指定文件路径运行sass-migrator：

sass-migrator division node_modules/@bigcommerce/citadel/dist/tools/toolkit.scss

注意：此操作会直接修改node_modules中的文件，建议配合patch-package持久化修改

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