Webpack 中 Node.js ESM 模块打包的原型继承问题解析

问题背景

在现代 JavaScript 开发中，Webpack 作为主流的模块打包工具，支持将 Node.js 应用打包为单个文件。当开发者尝试将使用 CommonJS 模块系统的 Node.js 库（如 jimp 和 pngjs）打包为 ESM 格式时，可能会遇到原型继承失效的问题。

核心问题表现

在打包后的代码中，当使用 util.inherits() 方法进行原型继承时，会抛出错误："The 'superCtor.prototype' property must be of type object. Received undefined"。这是因为：

1. 原始代码中的 stream 模块通过 CommonJS 方式引入
2. 经过 Webpack 打包为 ESM 格式后，模块的原型链信息丢失
3. util.inherits() 方法无法找到父类的 prototype 属性

问题根源分析

ESM 模块系统与 CommonJS 在模块导出机制上有本质区别：

• CommonJS 导出的是完整的对象，包含原型链
• ESM 导出的是命名空间对象，默认情况下不保留原型信息

当 Webpack 将 CommonJS 模块打包为 ESM 时，默认使用命名空间导入方式，导致原型信息丢失。

解决方案

Webpack 提供了两种解决方案：

方案一：全局配置 externalsType

externalsType: "node-commonjs"

这种配置会告诉 Webpack 对所有外部依赖使用 CommonJS 风格的引入方式。

方案二：灵活的外部依赖配置

externals: function({ request }, callback) {
  if (/^node:/.test(request) || builtinModules.includes(request)) {
    return callback(null, 'node-commonjs ' + request);
  }
  callback();
}

这种方式可以更精细地控制哪些模块使用 CommonJS 方式引入。

实现原理

当使用 node-commonjs 方式处理外部依赖时，Webpack 会生成如下代码：

import { createRequire as __WEBPACK_EXTERNAL_createRequire } from "node:module";

module.exports = __WEBPACK_EXTERNAL_createRequire(import.meta.url)("stream");

这种实现方式：

1. 使用 ESM 的 import.meta.url 获取当前模块的 URL
2. 通过 createRequire 创建 CommonJS 风格的 require 函数
3. 用传统方式引入 Node.js 内置模块

从而保留了完整的原型链信息，确保 util.inherits() 等依赖原型的方法正常工作。

最佳实践建议

1. 对于 Node.js 后端项目打包，优先考虑使用 externalsType: "node-commonjs"
2. 对于混合前端/后端的项目，使用函数式 externals 配置进行精细控制
3. 对于需要同时支持浏览器和 Node.js 的库，考虑提供不同的打包配置
4. 新项目建议直接使用 ESM 规范编写代码，避免原型继承的用法

总结

Webpack 的模块打包机制非常灵活，能够处理各种模块系统之间的转换。理解不同模块系统的差异以及 Webpack 的配置选项，可以帮助开发者解决类似的原型继承问题。对于 Node.js 项目的打包，合理使用 externalsType 或函数式 externals 配置是确保代码正常运行的关键。