Storybook/webpack无法通过别名识别组件及嵌套组件问题

问题表现 #

• Story文件用相对路径引入组件时，可正常加载、展示组件内容
• 改用项目通用的@别名（通常指向src目录）引入组件时，触发模块找不到报错；组件内部如果用@别名引用嵌套子组件，也会触发同类报错

两种引入写法对比如下：
✅ 正常运行的相对路径写法

import FooterComponent from '../components/HeaderAndFooter/FooterComponent.vue';

export default {
  title: 'Footer',
  component: FooterComponent,
  argTypes: {
  },
};

❌ 触发报错的别名写法

import FooterComponent from '@/components/HeaderAndFooter/FooterComponent.vue';

修复方法 #

核心是给Storybook的构建配置添加和项目一致的路径别名规则，根据你项目的构建工具选对应配置即可，配置文件统一为项目根目录下的.storybook/main.js：

Webpack项目（Vue CLI、旧版Vue项目通用） #

1. 在配置文件顶部引入Node原生path模块处理路径

const path = require('path');

2. 在配置对象中添加/修改webpackFinal字段，注入别名解析规则，原有其他配置（stories、addons等）全部保留不动

module.exports = {
  // 原有其他配置不要删
  webpackFinal: async (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      // 路径根据.storybook文件夹和src文件夹的相对位置调整，确保最终指向src目录的绝对路径
      '@': path.resolve(__dirname, '../src'),
    };
    return config;
  },
};

Vite项目 #

不要配置webpackFinal，改用viteFinal字段，规则和你项目vite.config.js里的别名配置保持一致即可

const path = require('path');
module.exports = {
  // 原有其他配置不要删
  async viteFinal(config) {
    config.resolve.alias = {
      ...config.resolve.alias,
      '@': path.resolve(__dirname, '../src'),
    };
    return config;
  },
};

注意事项 #

• 配置修改完成后必须重启Storybook开发服务，配置才会生效
• 如果配置后依然报模块找不到的错误，优先检查path.resolve里的层级是否正确，确保路径最终指向项目的src目录，绝大多数配置不生效都是路径层级写错导致的

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