Vue3项目Storybook中Scss样式不生效问题求助

问题根源分析 #

1. Storybook独立环境未接入项目全局样式：Vue本地开发时会自动加载你配置的全局样式，但Storybook是单独的构建环境，需要手动配置引入。
2. 之前的viteFinal配置错误：直接覆盖了Storybook默认的Vite配置，导致构建流程崩溃，故事无法加载。
3. 组件内SCSS路径解析异常：Storybook的路径规则和Vue项目本地存在差异，尤其是使用别名的场景，容易导致样式文件找不到。

具体解决办法 #

1. 最简单的全局样式导入：使用preview.js #

直接在.storybook/preview.js中导入全局SCSS，这是Storybook官方最推荐的方式，完全不会干扰Vite配置，避免构建崩溃：

// .storybook/preview.js
// 替换成你项目里全局样式的实际路径
import '../src/styles/global.scss';

// 以下为默认参数配置，无需修改
export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },
};

重启Storybook后即可看到全局样式生效。

2. 自定义Vite配置：必须用mergeConfig合并 #

如果需要通过Vite注入全局SCSS变量等内容，绝对不能直接替换Vite配置，需用mergeConfig将自定义配置与Storybook默认配置合并：

// .storybook/main.js
import { mergeConfig } from 'vite';

export default {
  stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
  ],
  framework: {
    name: '@storybook/vue3-vite',
    options: {},
  },
  docs: {
    autodocs: 'tag',
  },
  viteFinal: async (config) => {
    // 合并自定义配置与默认配置，禁止直接返回新对象
    return mergeConfig(config, {
      css: {
        preprocessorOptions: {
          scss: {
            // 全局注入SCSS变量文件（纯样式文件推荐用preview.js导入）
            additionalData: `@import "../src/styles/variables.scss";`,
          },
        },
      },
    });
  },
};

之前的问题就是因为直接返回新的Vite配置，覆盖了Storybook自带的必要配置，导致构建失败。

3. 组件内样式缺失：检查路径与别名 #

如果仅单个组件样式缺失：

• 确认组件内的SCSS导入使用相对路径，比如@import './styles.scss'，避免直接使用绝对路径（除非配置了别名）。
• 若项目使用@/这类别名，需在Storybook的Vite配置中同步：

// .storybook/main.js
import { mergeConfig } from 'vite';
import path from 'path';

export default {
  // ...其他配置
  viteFinal: async (config) => {
    return mergeConfig(config, {
      resolve: {
        alias: {
          '@': path.resolve(__dirname, '../src'),
        },
      },
    });
  },
};

4. 依赖版本兼容性检查 #

确保以下依赖版本匹配：

• @storybook/vue3-vite 与Storybook核心版本均为7.x
• sass 版本使用1.32.0及以上（与Vue3、Vite兼容）
• vite 版本符合@storybook/vue3-vite的peer依赖要求（查看其package.json即可确认）

验证步骤 #

1. 删除node_modules和lock文件，重新安装依赖（避免版本冲突）
2. 执行npm run storybook重启服务
3. 先检查全局样式（如页面背景、全局字体）是否生效，再验证单个组件样式

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