CSS怎么在Storybook中为组件引入独立样式环境_配置preview.js加载全局样式

在Storybook中为组件引入独立样式环境：一份避坑指南

为Storybook中的组件配置独立的样式环境，听起来像是加一行代码的事，但实际操作时，“为什么我的全局样式没生效？” 这个问题却频频出现。今天，我们就来彻底厘清这里面的门道。

最直接、也最不容易出错的方法，就是在 preview.js（或 preview.ts）里直接 import 你的全局CSS文件。这种方式简单可靠，不依赖复杂的Webpack配置，也不需要额外的loader，从Storybook v6.5到最新的v9.x版本基本都适用。

但这里有个关键前提：它只负责注入纯CSS规则。如果你的项目依赖Sass变量、mixin或者嵌套语法，那光靠这个import是远远不够的。

preview.js 中 import 全局 CSS 是否生效？

先给个明确的判断清单：

• ✅ 生效：只要路径正确且文件为纯CSS或已编译的SCSS/CSS，通过preview.js引入的样式就能被Storybook的预览iframe成功加载。
• ❌ 不生效的常见原因：
  • 路径错误：比如从.storybook目录出发，却用了./src/style.css这样的相对路径（正确写法通常是../src/style/index.css）。
  • 文件语法错误：不小心把未编译的.scss文件直接import了进来。
  • 跨域或路径不可达：CSS文件内部使用了@import url(...)，但引用的资源无法访问。
  • 误用CSS Modules：引入了xxx.module.css这类文件，它们默认是局部作用域的，不会全局注入。

正确的引入姿势是这样的：

import '../src/style/reset.css';
import '../src/style/theme.css';

为什么不能在 preview.js 里 import Sass 文件？

道理其实很简单。preview.js运行在Ja vaScript的上下文中，它只是一个执行环境，而不是样式构建的流水线。当你试图import '../src/style/variables.scss'时，控制台很可能会抛出一个熟悉的错误：You may need an appropriate loader to handle this file type。

这是因为Sass文件（.scss / .sass）必须由sass-loader在Webpack的构建阶段进行编译处理，Ja vaScript运行时根本无法直接“理解”那些变量和混入语法。

所以，结论很清晰：

立即学习“前端免费学习笔记（深入）”；

• 如果你需要的是全局Sass变量、mixin或函数，那么必须通过配置webpackFinal中的additionalData来实现。
• 如果你的样式已经是编译好的CSS（比如Tailwind生成的文件，或者经过PostCSS处理后的输出），那么直接import到preview.js里是最省事的。

webpackFinal 配置中如何安全注入 Sass 全局变量？

这才是让所有组件故事都能自动识别$primary-color这类变量的唯一正确途径。配置的核心在于几个细节：

• 匹配正确的规则：必须用正则（如/.s[ac]ss$/）精准匹配到Sass文件。
• 正确使用additionalData：注入的字符串要用反引号包裹，并且@import的路径最好通过path.resolve转换为绝对路径，避免歧义。
• 避免规则冲突：检查是否已经存在处理scss的rule，不要重复添加，以免覆盖或冲突。

下面是一个推荐的配置示例（写在.storybook/main.js中）：

const path = require('path');

module.exports = {
  // ...其他配置
  webpackFinal: async (config) => {
    config.module.rules.forEach(rule => {
      if (rule.test && rule.test.toString().includes('scss')) {
        rule.use.forEach(loader => {
          if (loader.loader?.includes('sass-loader')) {
            loader.options = {
              ...loader.options,
              additionalData: `@import "${path.resolve(__dirname, '../src/style/variables.scss')}";`,
            };
          }
        });
      }
    });
    return config;
  },
};

在这个过程中，有几个坑需要特别注意：

• 把additionalData错误地配置到了css-loader上（这完全无效）。
• 路径中使用了像@/这样的别名，但在Webpack配置中没有对应的alias解析（稳妥起见，直接用path.resolve）。
• 项目中存在多个sass-loader实例，导致变量被意外覆盖或丢失。

说到底，问题的关键从来不是“加一行import”这个动作本身，而是要分清楚你引入的样式属于「运行时注入」还是「构建时编译」。前者交给preview.js，后者必须通过webpackFinal来配置——把这两者混为一谈，功夫可就白费了。