NX单体仓库启动Storybook报错：TypeError: 'compilation'参数需为Compilation实例

在NX单体仓库中执行以下命令启动Storybook时出现错误：
nx run projectName:storybook nx storybook projectName

错误信息 #

9% setup compilation SourceMapDevToolPlugin
C:\Users\userName\Documents\Git\bft3\node_modules\@angular-devkit\build-angular\node_modules\webpack\lib\javascript\JavascriptModulesPlugin.js:143
                        throw new TypeError(
                              ^

TypeError: The 'compilation' argument must be an instance of Compilation
    at Function.getCompilationHooks (C:\Users\userName\Documents\Git\bft3\node_modules\@angular-devkit\build-angular\node_modules\webpack\lib\javascript\JavascriptModulesPlugin.js:143:10)
    at SourceMapDevToolModuleOptionsPlugin.apply (C:\Users\userName\Documents\Git\bft3\node_modules\@angular-devkit\build-angular\node_modules\webpack\lib\SourceMapDevToolModuleOptionsPlugin.js:50:27)
    at C:\Users\userName\Documents\Git\bft3\node_modules\@angular-devkit\build-angular\node_modules\webpack\lib\SourceMapDevToolPlugin.js:163:53
    at Hook.eval [as call] (eval at create (C:\Users\userName\Documents\Git\bft3\node_modules\webpack\node_modules\tapable\lib\HookCodeFactory.js:19:10), <anonymous>:374:1)
    at Hook.CALL_DELEGATE [as _call] (C:\Users\userName\Documents\Git\bft3\node_modules\webpack\node_modules\tapable\lib\Hook.js:14:14)
    at Compiler.newCompilation (C:\Users\userName\Documents\Git\bft3\node_modules\webpack\lib\Compiler.js:1122:26)
    at C:\Users\userName\Documents\Git\bft3\node_modules\webpack\lib\Compiler.js:1166:29
    at _next0 (eval at create (C:\Users\userName\Documents\Git\bft3\node_modules\webpack\node_modules\tapable\lib\HookCodeFactory.js:33:10), <anonymous>:41:1)
    at eval (eval at create (C:\Users\userName\Documents\Git\bft3\node_modules\webpack\node_modules\tapable\lib\HookCodeFactory.js:33:10), <anonymous>:55:1)
    at processTicksAndRejections (node:internal/process/task_queues:96:5)

依赖排查结果（yarn list --pattern "webpack"） #

├─ @angular-devkit/build-angular@14.2.9
│  └─ webpack@5.74.0
├─ @angular-devkit/build-webpack@0.1402.9
├─ @cypress/webpack-preprocessor@5.15.5
├─ @ngtools/webpack@14.2.9
├─ @nrwl/angular@15.0.13
│  └─ webpack-merge@5.7.3
├─ @nrwl/cypress@15.0.13
│  └─ fork-ts-checker-webpack-plugin@7.2.13
├─ @nrwl/webpack@15.0.13
│  ├─ copy-webpack-plugin@10.2.4
│  ├─ fork-ts-checker-webpack-plugin@7.2.13
│  └─ webpack-dev-server@4.11.1
├─ @storybook/builder-webpack4@6.5.13
│  ├─ terser-webpack-plugin@4.2.3
│  ├─ webpack-dev-middleware@3.7.3
│  ├─ webpack-sources@1.4.3
│  ├─ webpack-virtual-modules@0.2.2
│  └─ webpack@4.46.0
│     └─ terser-webpack-plugin@1.4.5
├─ @storybook/builder-webpack5@6.5.13
│  ├─ fork-ts-checker-webpack-plugin@6.5.2
│  ├─ html-webpack-plugin@5.5.0
│  └─ webpack-dev-middleware@4.3.0
├─ @storybook/core-common@6.5.13
│  ├─ fork-ts-checker-webpack-plugin@6.5.2
│  ├─ terser-webpack-plugin@1.4.5
│  ├─ webpack-sources@1.4.3
│  └─ webpack@4.46.0
├─ @storybook/core-server@6.5.13
│  ├─ terser-webpack-plugin@1.4.5
│  ├─ webpack-sources@1.4.3
│  └─ webpack@4.46.0
├─ @storybook/manager-webpack4@6.5.13
│  ├─ terser-webpack-plugin@4.2.3
│  ├─ webpack-dev-middleware@3.7.3
│  ├─ webpack-sources@1.4.3
│  ├─ webpack-virtual-modules@0.2.2
│  └─ webpack@4.46.0
│     └─ terser-webpack-plugin@1.4.5
├─ @storybook/manager-webpack5@6.5.13
│  ├─ html-webpack-plugin@5.5.0
│  └─ webpack-dev-middleware@4.3.0
├─ @types/webpack-env@1.18.0
├─ @types/webpack-sources@3.2.0
├─ @types/webpack@4.41.33
├─ case-sensitive-paths-webpack-plugin@2.4.0
├─ copy-webpack-plugin@11.0.0
├─ css-minimizer-webpack-plugin@3.4.1
├─ fork-ts-checker-webpack-plugin@4.1.6
├─ html-webpack-plugin@4.5.2
├─ license-webpack-plugin@4.0.2
├─ pnp-webpack-plugin@1.6.4
├─ terser-webpack-plugin@5.3.6
├─ tsconfig-paths-webpack-plugin@3.5.2
├─ webpack-bundle-analyzer@4.7.0
├─ webpack-dev-middleware@5.3.3
├─ webpack-dev-server@4.11.0
├─ webpack-filter-warnings-plugin@1.2.1
├─ webpack-hot-middleware@2.25.3
├─ webpack-log@2.0.0
├─ webpack-merge@5.8.0
├─ webpack-node-externals@3.0.0
├─ webpack-sources@3.2.3
├─ webpack-subresource-integrity@5.1.0
├─ webpack-virtual-modules@0.4.6
└─ webpack@5.75.0

问题分析与解决方案 #

1. 核心原因：Webpack多版本冲突 #

从依赖输出可以明确看到项目同时存在Webpack 4和Webpack 5两个大版本：

• Webpack 5.x：@angular-devkit/build-angular依赖webpack@5.74.0，根目录直接依赖webpack@5.75.0
• Webpack 4.x：多个Storybook核心包（如@storybook/core-common、@storybook/builder-webpack4）依赖webpack@4.46.0

错误信息中的TypeError正是因为不同版本Webpack的Compilation类实例不兼容导致的——Webpack 4的插件试图调用Webpack 5的编译实例，类型校验失败抛出错误。

2. 具体修复方案 #

• 强制统一Webpack版本：在package.json中添加resolutions字段（Yarn支持），强制所有依赖使用Webpack 5.x版本：

"resolutions": {
  "webpack": "^5.75.0"
}

执行yarn install重新安装依赖，确保所有包都使用统一的Webpack 5版本。

• 指定Storybook使用Webpack 5构建器：如果暂时不想升级Storybook，在项目的.storybook/main.js中明确指定Webpack 5构建器：

module.exports = {
  core: {
    builder: '@storybook/builder-webpack5'
  }
};

同时安装对应依赖：yarn add -D @storybook/builder-webpack5 @storybook/manager-webpack5

• 升级Storybook版本：Storybook 6.5.x对Webpack 5的支持不够完善，建议升级到Storybook 7.x版本，它对Webpack 5的适配更成熟，且与NX 15.x兼容性更好。

3. 额外排查步骤 #

• 检查NX与Storybook版本兼容性：NX 15.0.13与Storybook 6.5.x可能存在适配问题，确认官方兼容矩阵匹配版本。
• 清理缓存：执行nx reset清理NX缓存，删除node_modules和yarn.lock后重新安装，避免缓存残留导致的版本问题。

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