运行npm run storybook时出现Field 'browser'别名配置无效错误

问题现象 #

执行npm run storybook时触发以下错误：

Field 'browser' doesn't contain a valid alias configuration
    resolve as module
      D:\FullStack\UI\react-uikit\node_modules\@testing-library\user-event\dist\utils\misc\node_modules doesn't exist or is not a directory  
      D:\FullStack\UI\react-uikit\node_modules\@testing-library\user-event\dist\utils\node_modules doesn't exist or is not a directory       
      D:\FullStack\UI\react-uikit\node_modules\@testing-library\user-event\dist\node_modules doesn't exist or is not a directory
      D:\FullStack\UI\react-uikit\node_modules\@testing-library\user-event\node_modules doesn't exist or is not a directory
      D:\FullStack\UI\react-uikit\node_modules\@testing-library\node_modules doesn't exist or is not a directory
      D:\FullStack\UI\react-uikit\node_modules\node_modules doesn't exist or is not a directory
      looking for modules in D:\FullStack\UI\react-uikit\node_modules
        D:\FullStack\UI\react-uikit\node_modules\@testing-library\dom doesn't exist
      D:\FullStack\UI\node_modules doesn't exist or is not a directory
      D:\FullStack\node_modules doesn't exist or is not a directory
      D:\node_modules doesn't exist or is not a directory
      looking for modules in D:\FullStack\UI\react-uikit\node_modules\react-scripts\node_modules
        D:\FullStack\UI\react-uikit\node_modules\react-scripts\node_modules\@testing-library\dom doesn't exist

WARN Broken build, fix the error above.
WARN You may need to refresh the browser.

npm start和npm run test可正常运行，仅Storybook启动失败，已尝试重新安装依赖、创建新项目均无效。

项目依赖配置（package.json） #

{
  "name": "react-uikit",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@testing-library/jest-dom": "^5.16.5",
    "@testing-library/react": "^13.4.0",
    "@testing-library/user-event": "^13.5.0",
    "@types/jest": "^27.5.2",
    "@types/node": "^16.18.13",
    "@types/react": "^18.0.28",
    "@types/react-dom": "^18.0.11",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-scripts": "5.0.1",
    "styled-components": "^5.3.6",
    "typescript": "^4.9.5",
    "web-vitals": "^2.1.4"
  },
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject",
    "storybook": "start-storybook -p 6006 -s public",
    "build-storybook": "build-storybook -s public"
  },
  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest"
    ],
    "overrides": [
      {
        "files": [
          "**/*.stories.*"
        ],
        "rules": {
          "import/no-anonymous-default-export": "off"
        }
      }
    ]
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "devDependencies": {
    "@storybook/addon-actions": "^6.5.16",
    "@storybook/addon-essentials": "^6.5.16",
    "@storybook/addon-interactions": "^6.5.16",
    "@storybook/addon-links": "^6.5.16",
    "@storybook/builder-webpack5": "^6.5.16",
    "@storybook/manager-webpack5": "^6.5.16",
    "@storybook/node-logger": "^6.5.16",
    "@storybook/preset-create-react-app": "^4.1.2",
    "@storybook/react": "^6.5.16",
    "@storybook/testing-library": "^0.0.13",
    "babel-plugin-named-exports-order": "^0.0.2",
    "jest": "^29.4.3",
    "prop-types": "^15.8.1",
    "webpack": "^5.75.0"
  }
}

解决方法 #

1. 手动安装@testing-library/dom #

错误提示找不到@testing-library/dom，虽为@testing-library/user-event的间接依赖，但Storybook环境可能未正确识别，手动安装该包：

npm install @testing-library/dom --save-dev

2. 调整Storybook的Webpack配置 #

在项目根目录创建或修改.storybook/main.js，添加模块解析规则，确保Webpack能正确定位@testing-library相关包：

const path = require('path');

module.exports = {
  stories: ["../src/**/*.stories.mdx", "../src/**/*.stories.@(js|jsx|ts|tsx)"],
  addons: [
    "@storybook/addon-links",
    "@storybook/addon-actions",
    "@storybook/addon-essentials",
    "@storybook/addon-interactions",
    "@storybook/preset-create-react-app",
  ],
  framework: "@storybook/react",
  core: {
    builder: "@storybook/builder-webpack5",
  },
  webpackFinal: async (config) => {
    config.resolve.modules = [
      ...(config.resolve.modules || []),
      "node_modules",
    ];
    config.resolve.alias = {
      ...(config.resolve.alias || {}),
      "@testing-library": path.resolve(__dirname, "../node_modules/@testing-library"),
    };
    return config;
  },
};

3. 降级@testing-library/user-event版本 #

当前使用的@testing-library/user-event@13.5.0可能与Storybook v6.5.x存在兼容性问题，尝试降级到稳定版本：

npm install @testing-library/user-event@14.4.3 --save-dev

4. 清理缓存并重新安装依赖 #

执行以下命令清理缓存、删除旧依赖文件后重新安装：

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

内容的提问来源于stack exchange，提问作者Dev gobind Ganguly