Nuxt V3中运行Storybook失败的技术问题求助

问题背景 #

在Nuxt v3中运行Storybook时遭遇报错，尝试社区多种方案未解决，首次使用Storybook与原子设计，调试受阻。

项目配置 #

package.json #

{
  "name": "nuxt-atomic",
  "private": true,
  "scripts": {
    "build": "nuxt build",
    "dev": "nuxt dev",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "postinstall": "nuxt prepare",
    "prepare": "husky install",
    "lint:js": "eslint --ext \"\\.ts,.vue\" --ignore-path .gitignore .",
    "lint:prettier": "prettier --check .",
    "lint": "yarn lint:js && yarn lint:prettier",
    "lintfix": "prettier --write --list-different . && yarn lint:js --fix",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
  },
  "devDependencies": {
    "@commitlint/cli": "^17.7.1",
    "@commitlint/config-conventional": "^17.7.0",
    "@nuxt/devtools": "latest",
    "@nuxtjs/eslint-config-typescript": "^12.1.0",
    "@nuxtjs/tailwindcss": "^6.8.0",
    "@storybook/addon-essentials": "^7.4.1",
    "@storybook/addon-interactions": "^7.4.1",
    "@storybook/addon-links": "^7.4.1",
    "@storybook/blocks": "^7.4.1",
    "@storybook/testing-library": "^0.2.0",
    "@storybook/vue3": "^7.4.1",
    "@storybook/vue3-vite": "^7.4.1",
    "@typescript-eslint/parser": "^6.7.0",
    "@vueuse/core": "^10.4.1",
    "@vueuse/nuxt": "^10.4.1",
    "autoprefixer": "^10.4.15",
    "eslint": "^8.49.0",
    "eslint-config-prettier": "^9.0.0",
    "eslint-plugin-prettier": "^5.0.0",
    "eslint-plugin-storybook": "^0.6.13",
    "nuxt": "^3.7.3",
    "postcss": "^8.4.29",
    "prettier": "^3.0.3",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "storybook": "^7.4.1",
    "storybook-addon-nuxt": "^1.3.3",
    "typescript": "^5.2.2"
  },
  "dependencies": {
    "@pinia/nuxt": "^0.4.11",
    "husky": "^8.0.3",
    "pinia": "^2.1.6"
  }
}

.storybook/main.ts #

import type { StorybookConfig } from "@storybook/vue3-vite";

const config: StorybookConfig = {
  stories: [
    "../stories/**/*.mdx",
    "../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)",
  ],
  addons: [
    "storybook-addon-nuxt",
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/addon-interactions",
  ],
  framework: {
    name: "@storybook/vue3-vite",
    options: {},
  },
  docs: {
    autodocs: "tag",
  },
};
export default config;

.storybook/preview.ts #

import type { Preview } from "@storybook/vue3";

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: "^on[A-Z].*" },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
  },
};

export default preview;

报错信息 #

运行yarn storybook时出现两类错误：

1. storybook-addon-nuxt 预设加载失败

WARN   Failed to load preset: {"type":"presets","name":"/Users/alirezahamid/Documents/Apps/nuxt-atomic/node_modules/storybook-addon-nuxt/dist/preset.js"} on level 1.
./node_modules/storybook-addon-nuxt/dist/preset.js:1
import { fileURLToPath } from 'node:url';
^^^^^^

SyntaxError: Cannot use import statement outside a module

2. @testing-library 导出不匹配

✘ [ERROR] No matching export in "node_modules/@testing-library/dom/dist/@testing-library/dom.esm.js" for import "default"

    node_modules/@testing-library/user-event/dist/esm/_interop/dtl.js:2:7:
      2 │ import def__default from '@testing-library/dom';
        ╵        ~~~~~~~~~~~~

解决方案 #

1. 修复 storybook-addon-nuxt 预设加载错误 #

该错误源于插件的预设文件为ES模块，但被当作CommonJS加载。可尝试：

• 升级storybook-addon-nuxt至最新版本，或降级到适配Storybook 7的稳定版本
• 暂时移除该插件，手动配置Nuxt环境：修改.storybook/main.ts，添加Vite自定义配置以兼容Nuxt路径别名和Vue插件

import type { StorybookConfig } from "@storybook/vue3-vite";
import { fileURLToPath, URL } from 'node:url';

const config: StorybookConfig = {
  stories: [
    "../stories/**/*.mdx",
    "../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)",
  ],
  addons: [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/addon-interactions",
  ],
  framework: {
    name: "@storybook/vue3-vite",
    options: {},
  },
  docs: {
    autodocs: "tag",
  },
  viteFinal: async (config) => {
    return {
      ...config,
      resolve: {
        alias: {
          '@': fileURLToPath(new URL('../src', import.meta.url)),
          '~~': fileURLToPath(new URL('../', import.meta.url)),
        },
      },
    };
  },
};
export default config;

2. 修复 @testing-library 导出不匹配问题 #

此错误为@testing-library/user-event与@testing-library/dom版本不兼容导致，解决方式：

• 安装兼容版本组合，执行命令：

yarn add -D @testing-library/dom@9.3.1 @testing-library/user-event@14.4.3

• 若暂时无需交互测试，可移除相关依赖：从package.json中删除@storybook/addon-interactions和@storybook/testing-library，并更新.storybook/main.ts的addons数组。

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