如何分离Storybook的.storybook与stories目录实现关注点隔离？

背景 #

默认情况下，Storybook.js集成到Create-React-App项目时，会生成.storybook和src/stories两个目录。从关注点分离的角度，Storybook属于独立于业务逻辑的工具代码，放在src下会混淆业务与工具边界，因此尝试将stories目录移入.storybook中。

问题现象 #

移动目录后，Storybook页面持续显示加载spinner，终端和浏览器控制台无报错；偶尔等待较长时间后会出现加载超时错误：

Loading chunk vendors-node_modules_babel_runtime_helpers_esm_assertThisInitialized_js-node_modules_babel_ru-6be1ea failed.

(timeout: http://localhost:6006/vendors-node_modules_babel_runtime_helpers_esm_assertThisInitialized_js-node_modules_babel_ru-6be1ea.iframe.bundle.js)

当前目录结构与配置 #

目录结构 #

• .storybook
  • /stories
  • /assets
  • main.ts

main.ts配置 #

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

const config: StorybookConfig = {
  stories: ["./stories/**/*.mdx", "./stories/**/*.stories.@(js|jsx|ts|tsx)"],
  staticDirs: ["./assets"],
};

已尝试的无效操作 #

• 创建父目录统一存放.storybook和stories，但运行npm run storybook时无法识别.storybook目录
• 查阅Webpack v5相关文档，未找到有效解决思路

解决方案 #

1. 修正main.ts的路径与Webpack配置 #

问题核心是Storybook无法正确解析业务组件路径和静态资源路径，需调整配置：

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

const config: StorybookConfig = {
  stories: ["./stories/**/*.mdx", "./stories/**/*.stories.@(js|jsx|ts|tsx)"],
  // 使用绝对路径指定静态资源目录
  staticDirs: [path.resolve(__dirname, "./assets")],
  webpackFinal: async (config) => {
    // 添加项目src目录到模块解析路径，确保stories能正确引用业务组件
    if (config.resolve?.modules) {
      config.resolve.modules.push(path.resolve(__dirname, "../src"));
    } else {
      config.resolve = { modules: [path.resolve(__dirname, "../src")] };
    }
    return config;
  },
};

export default config;

2. 清理Storybook缓存并重启 #

缓存可能导致路径解析异常，执行以下命令清理后重启：

rm -rf node_modules/.cache/storybook
npm run storybook

3. 检查stories中的组件引用路径 #

确保stories文件中引用业务组件的相对路径正确，例如：

// 原路径（src/stories下）
import Button from "../components/Button";

// 修改后（.storybook/stories下）
import Button from "../../src/components/Button";

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