Storybook中Field 'browser'别名配置无效问题排查求助

背景 #

主tsconfig.json里配置了路径别名，但搭配@nrwl/storybook@^13.1.4和webpack 5.37.0使用时，别名完全不生效，导入模块直接报找不到的错误。

报错信息 #

ERROR in ./libs/design-system/theme/src/provider.tsx 4:0-58
Module not found: Error: Can't resolve '@libs/shared/feature-platform' in '/Users/project/libs/design-system/theme/src'
resolve '@libs/shared/feature-platform' in '/Users/project/libs/design-system/theme/src'
  Parsed request is a module
  using description file: /Users/project/package.json (relative path: ./libs/design-system/theme/src)
    Field 'browser' doesn't contain a valid alias configuration
    resolve as module
      /Users/project/libs/design-system/theme/src/node_modules doesn't exist or is not a directory
      /Users/project/libs/design-system/theme/node_modules doesn't exist or is not a directory
      /Users/project/libs/design-system/node_modules doesn't exist or is not a directory
      /Users/project/libs/node_modules doesn't exist or is not a directory
      looking for modules in /Users/project/node_modules
        /Users/project/node_modules/@libs/shared doesn't exist
      /Users/project/Sources/node_modules doesn't exist or is not a directory
      /Users/project/node_modules doesn't exist or is not a directory
      /Users/node_modules doesn't exist or is not a directory
      /node_modules doesn't exist or is not a directory

当前配置 #

Storybook Webpack解析配置 #

{
  "extensions": [
    ".mjs", ".js",
    ".jsx", ".ts",
    ".tsx", ".json",
    ".cjs"
  ],
  "modules": [ "node_modules" ],
  "mainFields": [ "browser", "module", "main" ],
  "alias": {
    "@storybook/addons": "/Users/project/node_modules/@storybook/addons",
    "@storybook/api": "/Users/project/node_modules/@storybook/api",
    "@storybook/channels": "/Users/project/node_modules/@storybook/channels",
    "@storybook/channel-postmessage": "/Users/project/node_modules/@storybook/channel-postmessage",
    "@storybook/components": "/Users/project/node_modules/@storybook/components",
    "@storybook/core-events": "/Users/project/node_modules/@storybook/core-events",
    "@storybook/router": "/Users/project/node_modules/@storybook/router",
    "@storybook/theming": "/Users/project/node_modules/@storybook/theming",
    "@storybook/semver": "/Users/project/node_modules/@storybook/semver",
    "@storybook/client-api": "/Users/project/node_modules/@storybook/client-api",
    "@storybook/client-logger": "/Users/project/node_modules/@storybook/client-logger",
    "react": "/Users/project/node_modules/react",
    "react-dom": "/Users/project/node_modules/react-dom"
  },
  "fallback": {
    "path": "/Users/project/node_modules/path-browserify/index.js",
    "assert": "/Users/project/node_modules/browser-assert/lib/assert.js",
    "crypto": false
  },
  "plugins": [
    {
      "TsconfigPathsPlugin": {
        "source": "described-resolve",
        "target": "resolve",
        "extensions": [Array],
        "log": [Object],
        "baseUrl": "../../../",
        "absoluteBaseUrl": "/Users/project/",
        "matchPath": [Function (anonymous)]
      }
    }
  ]
}

主tsconfig.json配置 #

{
  "compilerOptions": {
    "sourceMap": true,
    "noEmit": true,
    "noImplicitAny": true,
    "strictBindCallApply": true,
    "noImplicitReturns": true,
    "noImplicitThis": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true,
    "importHelpers": true,
    "module": "esnext",
    "target": "es5",
    "moduleResolution": "node",
    "baseUrl": "./",
    "jsx": "react",
    "skipLibCheck": true,
    "esModuleInterop": true,
    "lib": [
      "dom",
      "es2021",
      "scripthost"
    ],
    "types": [
      "jest",
      "cypress",
      "node",
      "webpack-env"
    ],
    "paths": {
      "@libs/shared/feature-platform": [
        "libs/shared/feature-platform/src/index.ts"
      ]
    }
  }
}

问题根源 #

1. TsconfigPathsPlugin的baseUrl配置错误：从Webpack配置能看到，插件的baseUrl设成了../../../，但主tsconfig的baseUrl是项目根目录的./。这个相对路径是相对于Storybook配置文件所在目录计算的，导致插件读取的baseUrl和主tsconfig不匹配，没法正确解析别名映射。
2. Webpack未添加项目根目录到模块搜索路径：当前Webpack的modules只包含node_modules，没把项目根目录加进去，所以Webpack只会去node_modules里找模块，不会在项目根目录下查找别名对应的文件。

解决办法 #

办法1：修正TsconfigPathsPlugin配置 #

在Storybook的配置文件（一般是.storybook/main.js）里，明确指定插件使用项目根目录的tsconfig：

const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');

module.exports = {
  webpackFinal: async (config) => {
    // 移除旧的插件实例避免冲突
    config.resolve.plugins = config.resolve.plugins.filter(
      plugin => !(plugin instanceof TsconfigPathsPlugin)
    );
    // 添加正确配置的插件
    config.resolve.plugins.push(
      new TsconfigPathsPlugin({
        configFile: './tsconfig.json', // 指向项目根目录的tsconfig
        baseUrl: './' // 和主tsconfig保持一致
      })
    );
    return config;
  },
};

办法2：给Webpack添加项目根目录搜索路径 #

直接在Webpack的resolve配置里加入项目根目录：

module.exports = {
  webpackFinal: async (config) => {
    config.resolve.modules.push(process.cwd()); // 把项目根目录加入模块搜索列表
    return config;
  },
};

办法3：手动在Webpack alias中配置映射 #

如果上面两种方法无效，直接绕开插件，手动配置别名映射：

const path = require('path');

module.exports = {
  webpackFinal: async (config) => {
    config.resolve.alias['@libs/shared/feature-platform'] = path.resolve(__dirname, '../libs/shared/feature-platform/src/index.ts');
    return config;
  },
};

验证 #

修改配置后重启Storybook服务，重新编译项目，检查是否还存在模块找不到的错误。

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