GraphQL-Request项目中的ESM与CJS模块互操作性改进

背景介绍

在Node.js生态系统中，模块系统经历了从CommonJS(CJS)到ECMAScript Modules(ESM)的演进过程。随着Node.js对ESM支持的不断完善，越来越多的开源项目开始转向纯ESM模式。GraphQL-Request作为一款流行的GraphQL客户端库，在7.x版本也采用了纯ESM的实现方式。

问题发现

在Node.js 20.17及更高版本中，引入了一项重要特性：允许通过require()函数加载ESM模块。这项功能最初需要通过--experimental-require-module标志启用，在Node.js 23.0中已成为默认行为。然而，GraphQL-Request项目的package.json配置中exports字段的限制性设置阻碍了这一功能的正常使用。

技术分析

问题的核心在于package.json中的exports字段配置。原配置仅指定了import条件，这意味着模块只能通过ESM的import语法导入。这种配置虽然符合纯ESM包的规范，但在Node.js新版本支持require(esm)的场景下显得过于严格。

解决方案

项目维护者采纳了社区建议，对package.json进行了以下关键修改：

1. 移除了限制性的import条件
2. 添加了default导出路径
3. 简化了exports字段结构

修改后的配置允许模块既可以通过ESM的import语法导入，也可以通过CJS的require()函数加载，实现了更好的兼容性。

影响范围

这一改进带来了以下好处：

1. 向后兼容：不影响现有ESM方式的使用
2. 向前兼容：支持Node.js新版本的require(esm)特性
3. 降低迁移成本：使仍在使用CJS的项目能够平滑升级到GraphQL-Request 7.x

最佳实践建议

对于仍在使用CJS但希望升级GraphQL-Request的用户：

1. 确保Node.js版本在20.17+（带标志）或23.0+（无标志）
2. 更新到GraphQL-Request 7.1.1或更高版本
3. 可以继续使用require()语法，无需改为import

总结

GraphQL-Request项目的这一改进展示了Node.js生态系统中模块系统演进的实际案例。通过合理的package.json配置，项目可以在保持纯ESM实现的同时，为不同环境的用户提供更好的兼容性支持。这种平衡技术进步与用户体验的做法值得其他开源项目借鉴。