为何多阶段Docker构建的Webpack产物运行报错，单阶段却正常？

你的推测完全正确！这两个构建方式的核心差异，以及报错的原因，本质上和**node_modules的存在与否**以及Webpack的打包配置直接相关：

1. 单阶段构建 vs 多阶段构建的关键区别 #

• 单阶段构建：整个构建流程都在同一个容器镜像内完成，最终镜像里保留了项目根目录及各子package下完整的node_modules文件夹，同时包含你构建好的bundle.js。
• 多阶段构建的第二阶段：你仅从builder阶段复制了bundle.js这单个文件到新镜像中，完全没有将任何node_modules目录同步到这个阶段的容器里。

2. 为什么单阶段能正常运行，多阶段会报错？ #

这是因为你的Webpack配置里，大概率把debug这类依赖设置成了**externals（外部依赖）**。Webpack的externals配置会告诉打包工具：「这个模块不需要打包进bundle里，运行时直接从当前环境读取」。

在单阶段构建中，容器内有完整的node_modules，当bundle.js运行时，会按照Node.js的模块查找规则，从本地node_modules里找到debug模块，因此不会报错。

但在多阶段构建的第二阶段，镜像里根本不存在node_modules，自然找不到debug模块，也就抛出了Cannot find module 'debug'的错误。

验证与解决思路 #

如果你想确认这一点，可以检查项目的Webpack配置文件，看看是否有类似这样的配置：

module.exports = {
  // ...其他配置项
  externals: {
    debug: 'commonjs debug'
    // 或者其他形式的externals声明
  }
};

要解决多阶段构建的问题，有两种常见方案：

• 方案一：修改Webpack配置，移除debug的externals设置，让Webpack把debug直接打包到bundle.js中，这样就不再依赖外部的node_modules。
• 方案二：在多阶段构建的第二阶段，除了复制bundle.js，还要将必要的node_modules目录（比如项目根目录的node_modules，或者package-sitemap下的node_modules）同步到目标镜像里。

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