如何为Next.js+Storybook的Webpack配置添加专属路径别名？

你遇到的核心问题是：Storybook需要同时满足TypeScript类型校验和Webpack模块解析两个维度的路径别名配置，仅在webpackFinal中配置别名只解决了Webpack的模块查找问题，但TypeScript的类型检查依然依赖工作区根目录的tsconfig.json——而这个文件里没有@/*指向ui-lib源码的配置，因此会出现类型报错。

不需要修改工作区的tsconfig.json，只需给Storybook单独配置一套TS规则，同时同步Webpack的别名配置即可：

1. 创建Storybook专属TS配置文件 #

在.storybook目录下新建tsconfig.json，继承工作区的TS配置，同时添加Storybook专属的路径别名：

{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": [
        "../src/*",
        "../../packages/ui-lib/src/*"
      ]
    }
  },
  "include": [
    "../src/**/*",
    "../../packages/ui-lib/src/**/*",
    "./**/*"
  ]
}

这个配置只会对Storybook生效，不会影响工作区其他项目的TS校验。

2. 配置Storybook读取专属TS文件 #

修改.storybook/main.ts，指定typescript字段的tsconfigPath为刚创建的文件，同时完善webpackFinal的别名配置（注意用path.resolve计算绝对路径，避免相对路径的歧义）：

import path from 'path';
import type { StorybookConfig } from '@storybook/nextjs';

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-links', '@storybook/addon-essentials'],
  framework: {
    name: '@storybook/nextjs',
    options: {},
  },
  // 指定Storybook使用专属TS配置
  typescript: {
    tsconfigPath: './.storybook/tsconfig.json',
  },
  webpackFinal: async (config) => {
    if (config.resolve?.alias) {
      // 添加Webpack别名，和TS配置保持一致
      config.resolve.alias['@'] = [
        path.resolve(__dirname, '../src'),
        path.resolve(__dirname, '../../packages/ui-lib/src')
      ];
    }
    return config;
  },
};

export default config;

3. 验证配置是否生效 #

重启Storybook后，@/components这类导入会同时被Webpack正确解析，且TypeScript类型校验也能找到对应的源码文件，不会再报错。

• 仅配置webpackFinal：Webpack能找到模块，但TS类型校验仍用工作区tsconfig.json，缺少别名配置导致类型报错。
• path.resolve未生效：大概率是路径计算错误（比如.storybook目录下的__dirname指向.storybook，需要用../src指向项目根目录的src），或者没有同步TS配置的别名，导致类型校验环节仍不识别路径。

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