Redux Toolkit 中 codegen-openapi 模块的 ERR_REQUIRE_ESM 问题解析与解决方案

在使用 Redux Toolkit 的 codegen-openapi 模块时，开发者可能会遇到 ERR_REQUIRE_ESM 错误。这个问题通常发生在项目配置为 ES 模块（ESM）但尝试以 CommonJS 方式加载配置文件时。

问题现象

当项目中的 package.json 设置了 "type": "module" 时，系统会将所有 .js 文件视为 ES 模块。此时如果使用 codegen-openapi 工具加载 JavaScript 配置文件（如 openapi-config.js），就会抛出 ERR_REQUIRE_ESM 错误。

错误信息明确指出三种可能的解决方案：

1. 将配置文件重命名为 .cjs 扩展名
2. 使用动态 import() 语法
3. 将 package.json 中的 type 改为 commonjs

深层原因

这个问题的本质是 Node.js 模块系统的差异。ES 模块和 CommonJS 模块在加载机制上有显著不同：

• ES 模块使用 import/export 语法，支持顶层 await，具有静态分析特性
• CommonJS 使用 require/module.exports，是动态加载的

codegen-openapi 内部使用 require() 加载配置文件，这在 ES 模块环境下是不被允许的。

解决方案

1. 使用 JSON 配置文件（推荐）

最直接的解决方案是将配置文件从 JavaScript 转换为 JSON 格式。codegen-openapi 完全支持 JSON 格式的配置文件，这种方式避免了模块系统的兼容性问题。

{
  "apiFile": "./src/store/emptyApi.ts",
  "apiImport": "emptySplitApi",
  "outputFile": "./src/store/api.ts",
  "exportName": "api",
  "hooks": true
}

2. 修改文件扩展名

将配置文件从 openapi-config.js 重命名为 openapi-config.cjs。.cjs 扩展名明确告诉 Node.js 这是一个 CommonJS 模块。

3. 调整项目模块类型

如果项目可以接受，可以将 package.json 中的 "type": "module" 改为 "type": "commonjs"。但这种方法会影响整个项目的模块系统，可能不是最佳选择。

4. 使用动态导入

修改 codegen-openapi 的源码，将 require() 改为动态 import()。不过这种方法需要维护修改后的版本，不推荐用于生产环境。

最佳实践建议

1. 对于简单配置，优先使用 JSON 格式
2. 如果配置需要复杂逻辑，考虑使用 .cjs 扩展名
3. 保持项目模块系统的一致性，不要混用 ESM 和 CommonJS
4. 定期检查工具链的兼容性，特别是涉及模块系统的部分

总结

ERR_REQUIRE_ESM 错误是 Node.js 生态中模块系统过渡期的常见问题。通过理解 ESM 和 CommonJS 的差异，开发者可以灵活选择最适合自己项目的解决方案。对于 Redux Toolkit 的 codegen-openapi 工具，使用 JSON 配置文件是最简单可靠的解决方法。