Storybook 7中Sass-Loader变量修正后错误残留问题求助

问题说明 #

我使用Storybook 7和TypeScript构建React组件库，已在.storybook/main.ts中通过@storybook/addon-styling-webpack配置sass-resource-loader加载包含变量和基础样式的global.styles.scss文件，初始配置可正常构建且样式生效。

但当修改变量名（如将$color-primary改为$color-prim）时，控制台会出现预期的undefined variable错误；修正拼写恢复为$color-primary后，尽管Storybook可正常构建且样式正确应用，控制台的错误却持续存在。不仅变量拼写问题，任何SCSS语法错误在修正后都会残留错误提示，严重影响开发体验。

残留错误信息 #

ERROR in ./src/components/Button/_button.styles.scss (./node_modules/css-loader/dist/cjs.js!./node_modules/sass-loader/dist/cjs.js!./node_modules/sass-resources-loader/lib/loader.js??ruleSet[1].rules[14].use[3]!./src/components/Button/_button.styles.scss)
Module build failed (from ./node_modules/sass-loader/dist/cjs.js):
Undefined variable.
   ╷
17 │   color: $color-black;
   │          ^^^^^^^^^^^^
   ╵
  src/styles/base.scss 17:10                     @import
  src/components/Button/_button.styles.scss 2:9  root stylesheet
 @ ./src/components/Button/_button.styles.scss 8:6-248 22:17-24 26:7-21 52:25-39 53:36-47 53:50-64 57:6-67:7 58:54-65 58:68-82 64:42-53 64:56-70 66:21-28 77:0-218 77:0-218 78:22-29 78:33-47 78:50-64 55:4-68:5
 @ ./src/components/Button/Button.component.tsx 86:0-31
 @ ./src/components/Button/Button.stories.tsx 1:0-60 3:13-19 12:29-43 27:13-35 36:13-37 45:13-32 55:13-35 64:13-32 74:13-36
 @ ./src/ lazy ^\.\/.*$ include: (?:\/src(?:\/(?%21\.)(?:(?:(?%21(?:^%7C\/)\.).)*?)\/%7C\/%7C$)(?%21\.)(?=.)[^/]*?\.stories\.(js%7Cjsx%7Cmjs%7Cts%7Ctsx))$ chunkName: [request] namespace object ./components/Button/Button.stories.tsx ./components/Button/Button.stories
 @ ./storybook-stories.js 23:11-27:5
 @ ./storybook-config-entry.js 6:0-50 25:21-29 28:2-31:4 28:58-31:3 30:31-39

ERROR in ./src/global.styles.scss (./node_modules/css-loader/dist/cjs.js!./node_modules/sass-loader/dist/cjs.js!./node_modules/sass-resources-loader/lib/loader.js??ruleSet[1].rules[14].use[3]!./src/global.styles.scss)
Module build failed (from ./node_modules/sass-loader/dist/cjs.js):
Undefined variable.
   ╷
17 │   color: $color-black;
   │          ^^^^^^^^^^^^
   ╵
  src/styles/base.scss 17:10  @import
  src/global.styles.scss 2:9  root stylesheet
 @ ./src/global.styles.scss 8:6-229 22:17-24 26:7-21 52:25-39 53:36-47 53:50-64 57:6-67:7 58:54-65 58:68-82 64:42-53 64:56-70 66:21-28 77:0-199 77:0-199 78:22-29 78:33-47 78:50-64 55:4-68:5
 @ ./.storybook/preview.ts 1:0-35
 @ ./storybook-config-entry.js 9:1258-1331 33:2-36:4 33:1242-36:3

preview compiled with 2 errors

当前配置代码 #

.storybook/main.ts #

import type { StorybookConfig } from "@storybook/react-webpack5";
import path from 'path';

const config: StorybookConfig = {
  stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
  addons: [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/addon-onboarding",
    "@storybook/addon-interactions",
    "@storybook/addon-themes",
    ({
        name: "@storybook/addon-styling-webpack",
        options: {
          rules: [
            {
              test: /\.scss$/,
              use: [
                  "style-loader",
                  "css-loader",
                  "sass-loader",
                  {
                    loader: "sass-resources-loader",
                    options: {
                      resources: [ 
                        path.resolve(__dirname, "../src/global.styles.scss" )
                      ]
                    }
                  }
              ],
            }
          ],
        }
    })
  ],
  framework: {
    name: "@storybook/react-webpack5",
    options: {
      builder: {
        useSWC: true,
      },
    },
  },
  // address "React is not defined" error
  swc: () => ({
    jsc: {
      transform: {
        react: {
          runtime: "automatic"
        }
      }
    }
  }),
  typescript: {
    // required for JSDocs to work correctly
    reactDocgen: "react-docgen"
  },
  docs: {
    autodocs: "tag",
  }
};
export default config;

.storybook/preview.ts #

import type { Preview } from "@storybook/react";

import '../src/global.styles.scss';

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: "^on[A-Z].*" },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
    docs: {
      toc: true
    }
  },
};

export default preview;

排查修复方案 #

• 清理Storybook缓存：执行命令npx storybook build --clean，手动删除.storybook/.cache目录，然后重启Storybook。Webpack缓存可能保留了旧的编译结果，导致错误残留。
• 调整Loader顺序：当前sass-resource-loader在sass-loader之后，会导致全局资源在SCSS编译完成后才注入，正确顺序应该是sass-resource-loader放在sass-loader之前，确保全局变量在组件SCSS编译时已加载：

  // 修改main.ts中的SCSS规则use数组顺序
  use: [
    "style-loader",
    "css-loader",
    {
      loader: "sass-resources-loader",
      options: {
        resources: [path.resolve(__dirname, "../src/global.styles.scss")]
      }
    },
    "sass-loader"
  ]
  

• 检查全局样式导入逻辑：确认global.styles.scss中正确导入了定义$color-black的base.scss，且文件路径无误。如果base.scss依赖其他变量文件，也要确保这些文件被正确导入。
• 临时禁用SWC缓存：在main.ts的builder配置中添加cache: false，排除SWC缓存导致的问题：

  framework: {
    name: "@storybook/react-webpack5",
    options: {
      builder: {
        useSWC: true,
        cache: false // 禁用缓存测试
      },
    },
  }
  

• 避免重复导入全局样式：preview.ts中已导入global.styles.scss，组件SCSS文件中无需再次导入，否则可能导致编译冲突。确保组件样式仅通过sass-resource-loader注入全局变量。

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