Storybook 中解析 TypeScript 模块别名使用 tsconfig-paths-webpack-plugin 配置 webpackFinal 完整指南【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇技术指南聚焦 Storybook 中一个高频实战问题当项目在tsconfig.json中配置了路径别名path aliases后默认的 Webpack 构建无法解析这些别名导致 Storybook 渲染 Story 时报Module not found错误。文章将基于 Storybook 官方配置片段docs/_snippets/storybook-main-ts-module-resolution.md展开覆盖 CSF 3 与 CSF Next 两种配置体系的完整写法并结合 builder-webpack5 的源码讲清webpackFinal的底层执行时机同时给出框架自带别名的替代方案与调试方法帮助读者彻底解决Storybook 找不到 TypeScript 模块这一经典问题。问题背景Storybook 为何无法解析 tsconfig 中的路径别名Storybook 的 Webpack builder 提供零配置zero-config开箱即用的体验其基线配置覆盖了大多数常见项目场景。但基线配置并不知道你的项目在tsconfig.json的compilerOptions.paths中定义的路径别名例如{ compilerOptions: { baseUrl: ., paths: { /*: [src/*], components/*: [src/components/*] } } }当 Storybook 按上述配置构建时config.resolve中并不存在这些别名映射于是 Storybook 的preview iframe 在加载 Story 文件时会抛错典型的如Module not found: Cant resolve /components/Button。这一现象在 docs/builders/webpack.mdx 的 Troubleshooting 章节TypeScript modules are not resolved within Storybook与 docs/configure/webpack.mdxTypeScript Module Resolution中均有明确记录默认 Webpack 配置可能无法解析tsconfig文件中定义的模块别名需要借助tsconfig-paths-webpack-plugin配合webpackFinal扩展配置来解决。方案一借助 tsconfig-paths-webpack-plugin 读取 tsconfig 路径tsconfig-paths-webpack-plugin会读取项目的tsconfig.json把paths中的别名自动注入到 Webpack 的resolve.plugins从而让 Storybook 与 TypeScript 编译器使用同一套模块解析规则。这是 docs/_snippets/storybook-main-ts-module-resolution.md 给出的官方推荐做法以下是该文档中全部五种写法按配置体系与框架整理。CSF 3JavaScript 写法.storybook/main.jsimport TsconfigPathsPlugin from tsconfig-paths-webpack-plugin; export default { // Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc. framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], webpackFinal: async (config) { if (config.resolve) { config.resolve.plugins [ ...(config.resolve.plugins || []), new TsconfigPathsPlugin({ extensions: config.resolve.extensions, }), ]; } return config; }, };CSF 3TypeScript 写法.storybook/main.ts// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc. import type { StorybookConfig } from storybook/your-framework; import TsconfigPathsPlugin from tsconfig-paths-webpack-plugin; const config: StorybookConfig { framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], webpackFinal: async (config) { if (config.resolve) { config.resolve.plugins [ ...(config.resolve.plugins || []), new TsconfigPathsPlugin({ extensions: config.resolve.extensions, }), ]; } return config; }, }; export default config;CSF NextReact 框架的 TypeScript 写法CSF Next实验性特性推荐使用框架导出的defineMain辅助函数类型安全且会自动应用框架预设// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { defineMain } from storybook/your-framework/node; import TsconfigPathsPlugin from tsconfig-paths-webpack-plugin; export default defineMain({ framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], webpackFinal: async (config) { if (config.resolve) { config.resolve.plugins [ ...(config.resolve.plugins || []), new TsconfigPathsPlugin({ extensions: config.resolve.extensions, }), ]; } return config; }, });CSF NextReact 框架的 JavaScript 写法// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { defineMain } from storybook/your-framework/node; import TsconfigPathsPlugin from tsconfig-paths-webpack-plugin; export default defineMain({ framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], webpackFinal: async (config) { if (config.resolve) { config.resolve.plugins [ ...(config.resolve.plugins || []), new TsconfigPathsPlugin({ extensions: config.resolve.extensions, }), ]; } return config; }, });CSF NextAngular 框架的写法import { defineMain } from storybook/angular/node; import TsconfigPathsPlugin from tsconfig-paths-webpack-plugin; export default defineMain({ framework: storybook/angular, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], webpackFinal: async (config) { if (config.resolve) { config.resolve.plugins [ ...(config.resolve.plugins || []), new TsconfigPathsPlugin({ extensions: config.resolve.extensions, }), ]; } return config; }, });配置要点逐项拆解framework必须替换为项目实际使用的框架包例如storybook/react-webpack5、storybook/nextjs、storybook/angular等。只有 Webpack 系框架如react-webpack5、nextjs、angular、vue3-webpack5才适用本方案如果使用 Vite builder应改用 Vite 的resolve.alias配置。storiesStory 与 MDX 文档的 glob 匹配规则按项目目录结构调整。config.resolve.pluginsWebpack 的resolve.plugins数组用于注册自定义解析器Resolver Plugin。示例采用追加合并而非覆盖赋值——先展开已有的config.resolve.plugins || []再追加新的TsconfigPathsPlugin避免破坏 Storybook 内置解析逻辑。extensions: config.resolve.extensions将 Storybook 默认的扩展名列表通常包含.js、.jsx、.ts、.tsx、.mjs等透传给插件保证别名解析与文件扩展名解析行为一致。config.resolve存在性判断示例中的if (config.resolve)是防御性写法确保在不同框架/版本下拿到的基础配置结构稳定。方案二框架自带别名的零依赖做法并非所有场景都需要额外安装插件。如果你的框架自带默认别名例如 Next.js 的/指向项目根目录、Nuxt 的~/等可以直接在webpackFinal中把框架的别名规则合并进config.resolve.alias无需引入任何新依赖。针对最常见的别名指向src目录的场景docs/_snippets/storybook-main-ts-module-resolution-atsign-import.md 提供了完整的五段示例核心逻辑如下CSF 3 的 JS/TS 与 CSF Next 的写法结构一致仅入口不同import path from path; export default { // Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc. framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|ts|tsx)], webpackFinal: async (config) { if (config.resolve) { config.resolve.alias { ...config.resolve.alias, : path.resolve(process.cwd(), src), }; } return config; }, };import { defineMain } from storybook/your-framework/node; import path from path; export default defineMain({ framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|ts|tsx)], webpackFinal: async (config) { if (config.resolve) { config.resolve.alias { ...config.resolve.alias, : path.resolve(process.cwd(), src), }; } return config; }, });要点说明同样采用展开合并...config.resolve.alias保留已有别名再添加或覆盖别名防止把框架内置别名冲掉。path.resolve(process.cwd(), src)以 Storybook 进程的工作目录为基准解析出src的绝对路径请按实际源码目录调整。适用前提是项目别名数量少且规则简单如果tsconfig中定义了大量复杂路径映射仍建议使用方案一的tsconfig-paths-webpack-plugin避免手工维护别名与 tsconfig 不同步。深入原理webpackFinal 在 builder-webpack5 中的执行时机理解webpackFinal的底层行为有助于判断什么时候该用它、会不会覆盖内置配置。在 code/builders/builder-webpack5/src/presets/custom-webpack-preset.ts 中可以看到完整的执行链export async function webpack(config: Configuration, options: Options) { const { configDir, configType, presets } options; const coreOptions await presets.apply(core); let defaultConfig config; if (!coreOptions?.disableWebpackDefaults) { defaultConfig await createDefaultWebpackConfig(config, options); } const finalDefaultConfig await presets.apply(webpackFinal, defaultConfig, options); // ... const customConfig await loadCustomWebpackConfig(configDir); if (typeof customConfig function) { logger.info(Loading custom Webpack config (full-control mode).); return customConfig({ config: finalDefaultConfig, mode: configType }); } logger.info(Using default Webpack5 setup); return finalDefaultConfig; }从源码可以确认三点关键事实执行顺序Storybook 先通过createDefaultWebpackConfig生成基线配置再通过presets.apply(webpackFinal, ...)依次应用所有 preset包括 addon注册的webpackFinal钩子。因此你的webpackFinal收到的是已经过默认配置生成、可能已被其他 addon 修改的完整配置对象只需在其基础上做增量修改并原样返回。webpackFinal 与 webpack 的区别在 code/builders/builder-webpack5/src/types.ts 的类型定义中webpack的注释为在所有 addon 运行之后修改配置主要由 addons 使用而webpackFinal的注释为在每个 addon 都运行完毕之后修改或返回自定义 Webpack 配置。对用户而言webpackFinal是标准入口它属于StorybookConfigWebpack中显式保留给使用者扩展的字段。返回约定webpackFinal必须返回修改后的 config 对象async (config, options) Config参见 docs/api/main-config/main-config-webpack-final.mdx 的类型声明否则 Storybook 拿不到你的改动。第二个参数options中最常用的是configType取值为DEVELOPMENT或PRODUCTION可用于区分 dev/build 场景做差异化配置完整示例见 docs/_snippets/main-config-webpack-final.md。另外code/core/src/telemetry/storybook-metadata.ts 中通过!!mainConfig.webpackFinal检测用户是否定制了 Webpack这从侧面说明webpackFinal是 Storybook 识别自定义构建配置的官方信号字段。调试与验证确认别名是否真正生效配置完成后可通过以下方式验证启动开发模式运行yarn storybook dev或npm run storybook dev观察控制台是否还出现Module not found报错若报错消失说明别名解析已生效。导出 Webpack 配置排查Storybook CLI 支持--debug-webpack参数输出最终合并的 Webpack 配置开发模式与静态构建均可使用见 docs/builders/webpack.mdx开发模式yarn storybook dev --debug-webpack静态构建yarn storybook build --debug-webpack在输出的配置中检查resolve.plugins是否包含TsconfigPathsPlugin、resolve.alias是否包含映射即可确认配置是否被正确合并。类型层面检查CSF 3 写法中const config: StorybookConfig的显式类型标注会在编写main.ts时提供字段提示与拼写校验避免手误。注意事项与最佳实践保留 entry / output文档明确建议在修改webpackFinal中的config对象时负责任地处理尤其是保留entry与output属性参见 docs/builders/webpack.mdx对plugins数组应追加而非整体覆盖因为 Storybook 依赖HtmlWebpackPlugin生成 preview 页面。避免重复实例化webpackFinal在每次构建时都会执行若同时被 addon 和用户配置注册插件可能被多次添加。追加前可先判断config.resolve.plugins中是否已存在目标插件或接受官方示例的简单追加写法官方 snippet 未做去重多数场景下重复注册不会导致功能异常但注意不要在webpackFinal内做有副作用的全局操作。框架差异Next.js、Angular 等框架自带部分解析规则使用方案一时插件读取的是项目根目录的tsconfig.json请确保tsconfig中的paths是权威来源若项目存在多个 tsconfig如tsconfig.base.json被 extends 引用需确认插件版本支持或显式传入configFile选项。升级兼容本仓库的 Webpack builder 已基于 Webpack 5webpackVersion固定返回5Webpack 4 支持已被移除从旧版本升级 Storybook 时自定义 Webpack 配置需要按 Webpack 5 的迁移指南同步更新详见 docs/builders/webpack.mdx。小结TypeScript 模块别名在 Storybook 中无法解析根源在于 Webpack 默认解析器不感知tsconfig.json的paths映射。两条主路径即可覆盖绝大多数场景一是安装tsconfig-paths-webpack-plugin在webpackFinal中将其追加到config.resolve.plugins通用、自动同步 tsconfig二是对框架自带别名或简单别名直接展开合并config.resolve.alias零依赖。理解 builder-webpack5 中基线配置 → presets 应用 webpackFinal → 返回最终配置的执行链配合--debug-webpack导出配置验证即可稳定复现、定位并解决此类构建问题。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考