Storybook 8自动迁移后报错：@storybook/react-dom-shim缺少./dist/react-18

问题详情 #

执行Storybook 8自动迁移后，终端抛出以下错误：

[ERROR] Missing "./dist/react-18" specifier in "@storybook/react-dom-shim" package [plugin vite:dep-pre-bundle]

完整错误日志片段：

../../../node_modules/.pnpm/esbuild@0.20.2/node_modules/esbuild/lib/main.js:1374:27:
  1374 │         let result = await callback({

错误触发自注册的onResolve回调：

../../../node_modules/.pnpm/esbuild@0.20.2/node_modules/esbuild/lib/main.js:1293:20:
  1293 │       let promise = setup({

vite:dep-pre-bundle插件由如下导入触发：

../../../node_modules/.pnpm/@storybook+react@8.0.4_react-dom@18.2.0_react@18.2.0_typescript@5.0.4/node_modules/@storybook/react/dist/chunk-JXRZ2CQ5.mjs:4:46:
  4 │ import { unmountElement, renderElement } from '@storybook/react-dom-shim';

终端最终提示：

Node.js v18.12.1
 ELIFECYCLE  Command failed with exit code 7.

现象：Storybook的框架骨架能正常渲染，但故事内容的iframe完全崩溃。

技术栈与环境 #

• React 18.2
• Storybook 8.0.4
• Vite 5.2.2
• Sass 1.62.0
• 项目处于Monorepo结构，其他子项目仍使用Storybook 7

相关配置文件 #

package.json #

{
  "name": "@astreis/core",
  "version": "0.0.1",
  "description": "",
  "keywords": [],
  "author": "",
  "main": "index.ts",
  "dependencies": {
    "@astreis/utils": "workspace:^",
    "@floating-ui/react": "^0.25.1",
    "framer-motion": "^11.0.3",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-hook-form": "^7.46.1",
    "react-icons": "^5.0.0"
  },
  "devDependencies": {
    "@babel/core": "^7.21.4",
    "@babel/preset-react": "^7.24.1",
    "@storybook/addon-a11y": "^8.0.4",
    "@storybook/addon-actions": "^8.0.4",
    "@storybook/addon-essentials": "^8.0.4",
    "@storybook/addon-interactions": "^8.0.4",
    "@storybook/addon-links": "^8.0.4",
    "@storybook/addon-themes": "^8.0.4",
    "@storybook/blocks": "^8.0.4",
    "@storybook/builder-vite": "^8.0.4",
    "@storybook/manager-api": "^8.0.4",
    "@storybook/react": "^8.0.4",
    "@storybook/react-vite": "^8.0.4",
    "@storybook/test": "8.0.4",
    "@storybook/test-runner": "^0.17.0",
    "@storybook/theming": "^8.0.4",
    "@types/react": "^18.2.55",
    "@types/react-dom": "^18.2.19",
    "@typescript-eslint/eslint-plugin": "^7.0.0",
    "@typescript-eslint/parser": "^7.0.0",
    "@vitejs/plugin-react": "^4.0.4",
    "eslint": "^8.47.0",
    "eslint-config-prettier": "^9.0.0",
    "eslint-plugin-jsx-a11y": "^6.8.0",
    "eslint-plugin-prettier": "^5.0.1",
    "eslint-plugin-react": "^7.33.2",
    "eslint-plugin-react-hooks": "^4.6.0",
    "eslint-plugin-simple-import-sort": "^12.0.0",
    "eslint-plugin-storybook": "^0.8.0",
    "eslint-plugin-unused-imports": "^3.0.0",
    "prettier": "^3.0.2",
    "sass": "^1.62.0",
    "storybook": "^8.0.4",
    "stylelint": "^16.2.1",
    "stylelint-config-css-modules": "^4.4.0",
    "stylelint-config-standard-scss": "^13.0.0",
    "stylelint-prettier": "^5.0.0",
    "typescript": "^5.0.4",
    "vite": "^5.2.2",
    "vite-plugin-svgr": "^4.2.0"
  },
  "scripts": {
    "storybook": "storybook dev -p 6005",
    "build-storybook": "storybook build",
    "test-storybook": "test-storybook --url http://127.0.0.1:6005",
    "stylelint": "stylelint \"**/*{.module,}.{s,}css\"",
    "eslint": "eslint \"**/*.{j,t}s{x,}\""
  }
}

.storybook/main.ts #

export default {
  stories: [
    "../src/components/**/*.stories.@(js|jsx|ts|tsx)",
    "../src/docs/**/*.mdx",
  ],
  addons: [
    "@storybook/addon-a11y",
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/addon-interactions",
    "@storybook/addon-themes",
  ],
  framework: {
    name: "@storybook/react-vite",
  },
  core: {
    builder: '@storybook/builder-vite',
  },
  docs: {
    autodocs: true,
  },
};

vite.config.ts #

import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";
import svgr from "vite-plugin-svgr";

export default defineConfig({
  plugins: [react(), svgr()],
});

解决方案 #

方案1：强制统一依赖版本（Monorepo专属） #

由于Monorepo中同时存在SB7和SB8，可能出现@storybook/react-dom-shim版本不一致的问题。在根目录的package.json中添加版本覆盖规则：

• 若使用pnpm，添加：

"pnpm": {
  "overrides": {
    "@storybook/react-dom-shim": "^8.0.4"
  }
}

• 若使用yarn，添加：

"resolutions": {
  "@storybook/react-dom-shim": "^8.0.4"
}

添加后重新安装依赖：

pnpm install # 或 yarn install

方案2：清理缓存并重建 #

1. 删除本地依赖与锁文件：

rm -rf node_modules pnpm-lock.yaml # 对应yarn.lock或package-lock.json

2. 清除Storybook和Vite缓存：

npx storybook clean
pnpm dlx vite cache clean

3. 重新安装依赖并启动Storybook：

pnpm install
pnpm run storybook

方案3：跳过Vite预构建 #

在.storybook/main.ts中修改Vite配置，排除@storybook/react-dom-shim的预构建：

export default {
  // 保留原有配置...
  viteFinal: async (config) => {
    config.optimizeDeps = {
      ...config.optimizeDeps,
      exclude: [...(config.optimizeDeps?.exclude || []), '@storybook/react-dom-shim'],
    };
    return config;
  },
};

修改后重启Storybook即可。

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