NextJS项目中Storybook引入第三方NPM模块报错问题咨询

安全阿岳

2026-10-6

问题成因

Swiper v8及以上版本为纯ESM规范包，仅提供ESM格式导出，不再兼容CommonJS规范。Storybook默认模块解析规则优先适配CommonJS包，未针对纯ESM第三方包的路径导出规则做适配，因此无法识别swiper/react、swiper/css这类导出路径。
Storybook默认的构建配置（Webpack/Vite）未将swiper纳入需要转译的依赖范围，导致模块路径无法被正确解析。
Next.js 13+ 默认moduleResolution配置为bundler，若Storybook的TypeScript解析规则与项目配置不匹配，会进一步加重路径解析错误。

解决方案

Webpack版Storybook适配（`sb init`默认生成的Next.js适配版为Webpack架构）

修改.storybook/main.js配置，添加webpackFinal规则：

module.exports = {
  // 保留原有stories、addons等配置不变
  webpackFinal: async (config) => {
    // 将swiper纳入ESM转译范围
    config.module.rules.push({
      test: /\.m?js$/,
      include: /node_modules\/swiper/,
      type: "javascript/auto",
    });
    // 扩展模块解析后缀
    config.resolve.extensions = [
      ...config.resolve.extensions,
      ".mjs",
      ".js",
      ".jsx",
      ".ts",
      ".tsx",
    ];
    return config;
  },
};

Vite版Storybook适配

修改.storybook/main.js配置，添加viteFinal规则：

module.exports = {
  // 保留原有stories、addons等配置不变
  async viteFinal(config) {
    config.optimizeDeps.include = [
      ...(config.optimizeDeps?.include || []),
      "swiper/react",
      "swiper/css",
    ];
    return config;
  },
};