Puppeteer项目中ESM与CommonJS模块兼容性问题解析

问题背景

在使用Puppeteer和@sparticuz/chromium组合进行PDF生成时，开发者可能会遇到一个典型的模块系统兼容性问题。具体表现为当尝试通过require()加载ES模块(ESM)时，Node.js会抛出错误，提示不支持直接require()ES模块。

错误现象

核心错误信息显示：

require() of ES Module /opt/node_modules/get-stream/source/index.js from /opt/node_modules/extract-zip/index.js not supported.
Instead change the require of /opt/node_modules/get-stream/source/index.js in /opt/node_modules/extract-zip/index.js to a dynamic import() which is available in all CommonJS modules.

这表明项目中存在ES模块和CommonJS模块混用的情况，而Node.js的模块系统在这两种规范间的互操作性存在限制。

技术原理

Node.js支持两种模块系统：

1. CommonJS (CJS) - 使用require()和module.exports
2. ES Modules (ESM) - 使用import和export

当CommonJS模块尝试通过require()加载ES模块时，Node.js会抛出ERR_REQUIRE_ESM错误。这是Node.js模块系统的设计决策，因为两种模块系统在加载机制、解析方式和执行环境上存在根本差异。

解决方案分析

临时解决方案

1. 版本降级法：通过package.json的overrides字段强制使用get-stream的6.0.1版本，该版本仍采用CommonJS规范：

{
  "overrides": {
    "get-stream": "6.0.1"
  }
}

2. 依赖降级法：如果问题由其他依赖(如ejs-lint)引起，可尝试降级到兼容版本(如^1.2.1)

长期解决方案

1. 统一模块系统：将整个项目迁移到ESM规范，使用import/export语法

2. 动态导入：修改相关代码，将require()改为动态import()：

// 替换前
const getStream = require('get-stream');

// 替换后
const getStream = await import('get-stream');

3. 模块包装：创建适配层，统一处理模块加载

最佳实践建议

1. 版本锁定：在关键依赖上使用精确版本号或版本范围限制

2. 环境一致性：确保开发、测试和生产环境的Node.js版本一致

3. 模块审计：定期检查项目依赖的模块规范变化

4. 渐进迁移：对于大型项目，可采用混合模式逐步迁移到ESM

总结

Puppeteer项目中的模块兼容性问题反映了Node.js生态向ESM过渡期的典型挑战。开发者需要理解两种模块系统的差异，并根据项目实际情况选择合适的解决方案。随着Node.js对ESM支持的不断完善，这类问题将逐步减少，但在过渡期内仍需保持警惕。