Webpack CSS Loader报错：SCSS变量处‘Unknown word’问题解决

问题 #

执行npm build时出现SCSS语法解析错误，错误信息如下：

asset main.js 901 KiB [emitted] (name: main) 1 related asset
asset icon.png 795 bytes [compared for emit] [from: src/styles/icon.png] (auxiliary name: main)
orphan modules 51.1 KiB (javascript) 975 bytes (runtime) [orphan] 17 modules
runtime modules 2.15 KiB 7 modules
javascript modules 710 KiB
  modules by path ./ 452 KiB
    modules by path ./src/ 449 KiB 54 modules
    ./index.js 3.26 KiB [built] [code generated]
    ./index.scss 39 bytes [built] [code generated] [1 error]
  modules by path ../ 258 KiB
    modules by path ../../common/temp/node_modules/.pnpm/@babel+runtime@7.22.11/node_modules/@...(truncated) 22.4 KiB 31 modules
    modules by path ../cursor-effects/ 13.2 KiB 5 modules
    modules by path ../../backend/ 155 KiB
      ../../backend/common/dist/main.js 134 KiB [built] [code generated]
      ../../backend/event-emitter/dist/main.js 20.9 KiB [built] [code generated]
    + 7 modules
./src/styles/icon.png 42 bytes (javascript) 795 bytes (asset) [built] [code generated]

ERROR in ./src/styles/_iconview.scss (../../common/temp/node_modules/.pnpm/css-loader@6.8.1_webpack-cli@5.1.4/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[1].use[1]!./src/styles/_iconview.scss)  
Module build failed (from ../../common/temp/node_modules/.pnpm/css-loader@6.8.1_webpack-cli@5.1.4/node_modules/css-loader/dist/cjs.js):

SyntaxError

(95:7) client\src\styles\_iconview.scss Unknown word

  93 |                  overflow: visible;
  94 |
> 95 |                  #{ $self }__icon {
     |                     ^
  96 |                          background-color: rgb(0 0 200 / 90%);
  97 |                  }
 @ ./index.scss.webpack[javascript/auto]!=!../../common/temp/node_modules/.pnpm/css-loader@6.8.1_webpack-cli@5.1.4/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[1].use[1]!../../common/temp/node_modules/.pnpm/sass-loader@13.3.2_sass@1.66.1_webpack@5.88.2/node_modules/sass-loader/dist/cjs.js??ruleSet[1].rules[1].use[2]!./index.scss 11:0-214 20:26-59
 @ ./index.scss
 @ ./index.js 32:0-22

项目Webpack配置如下：

const path = require("path");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const CssMinimizerPlugin = require("css-minimizer-webpack-plugin");

const mode = process.env.NODE_ENV || "development";
const minimize = mode === "production";
const plugins = [];

if (mode === "production") {
    plugins.push(new CssMinimizerPlugin());
}

module.exports = {
    mode,
    devtool: "source-map",
    entry: [path.resolve(__dirname, "index.js")],
    output: {
        library: "MyClientName",
        libraryTarget: "umd",
        umdNamedDefine: true,
        sourceMapFilename: "[file].map",
        filename: "[name].js",
    },
    optimization: {
        minimize,
    },
    plugins: [
        new MiniCssExtractPlugin({
            filename: "[name].css",
            chunkFilename: "[id].css",
        }),
        ...plugins,
    ],
    module: {
        rules: [
            {
                test: /\.(svg|png|jpe?g|gif|webp)$/,
                type: "asset/resource",
                exclude: /node_modules/,
                generator: {
                    filename: "[name][ext]",
                },
            },
            {
                test: /\.(sa|sc|c)ss$/,
                exclude: /node_modules/,
                use: [
                    MiniCssExtractPlugin.loader,
                    {
                        loader: "css-loader",
                        options: {
                            sourceMap: true,
                        },
                    },
                    {
                        loader: "sass-loader",
                        options: {
                            sourceMap: true,
                        },
                    },
                ],
            },
            {
                test: /\.html$/i,
                loader: "html-loader",
            },
            {
                test: /\.js$/,
                exclude: /node_modules/,
                use: {
                    loader: "babel-loader",
                },
            },
        ],
    },
};

该SCSS代码原本可正常编译，更新依赖版本后出现此问题，需排查原因并解决SCSS编译问题。

原因分析 #

错误提示指向SCSS中的#{ $self }__icon语法，css-loader无法识别该语法——这说明sass-loader没有先于css-loader处理SCSS变量插值，导致原始的SCSS语法直接被css-loader解析，而css-loader只能处理标准CSS，无法识别SCSS的变量插值语法。

更新依赖后出现该问题，大概率是sass-loader或sass的版本与当前webpack/css-loader版本不兼容，导致loader执行顺序或编译逻辑异常；或是依赖更新后，sass-loader的配置出现隐性变化，没有正确启用SCSS编译。

解决方案 #

1. 调整SCSS语法（快速验证） #

新版本sass对语法空格可能更严格，尝试去掉变量插值中的空格，将#{ $self }改为#{$self}，再重新编译测试。

2. 锁定兼容的依赖版本 #

查看sass-loader官方兼容说明，匹配当前webpack（5.x）、css-loader（6.x）的版本组合，卸载现有版本后重新安装：

# 卸载现有相关依赖
npm uninstall sass-loader sass css-loader
# 安装兼容版本示例（适配webpack 5.x）
npm install sass-loader@13.3.2 sass@1.66.0 css-loader@6.8.0 --save-dev

3. 显式配置sass-loader的编译器 #

在webpack配置中，给sass-loader指定使用dart-sass编译器，避免版本适配问题：

{
  loader: "sass-loader",
  options: {
    sourceMap: true,
    implementation: require('sass'), // 显式指定dart-sass
  },
}

4. 检查loader执行顺序 #

Webpack loader是从右到左执行的，当前配置中sass-loader在css-loader之后，顺序正确，但需确保没有其他webpack规则意外匹配了SCSS文件，干扰编译流程。

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