Rspress 项目中 lodash-es 模块引入问题解析与解决方案

问题背景

在 Rspress 项目构建过程中，开发者遇到了一个关于模块引入的典型问题。当项目构建完成后，在 @rspress/shared/dist/node-utils.js 文件中存在对 lodash-es 模块的 CommonJS 方式引入，而 lodash-es 是一个纯粹的 ESM 模块包，这导致了运行时错误。

错误现象

具体错误表现为 Node.js 运行时抛出的 ERR_REQUIRE_ESM 错误，提示开发者不能使用 require() 来引入 ESM 模块。错误信息明确指出，应该将 require 改为动态 import() 方式，因为动态导入在所有 CommonJS 模块中都可用。

技术分析

这个问题涉及到 Node.js 模块系统的几个关键概念：

1. CommonJS 与 ESM 模块系统的差异：CommonJS 使用 require() 同步加载模块，而 ESM 使用 import 异步加载模块。

2. lodash-es 的模块特性：lodash-es 是 lodash 的 ESM 版本，专门为现代 JavaScript 模块系统设计，只支持 ESM 导入方式。

3. 构建工具的处理：Rspress 在构建过程中将代码转换为 CommonJS 格式时，没有正确处理 ESM 依赖的引入方式。

影响范围

这个问题主要影响以下场景：

• 使用 @rspress/shared 中的 mergeDocConfig 方法的插件开发者
• 在 CommonJS 环境中运行 Rspress 构建产物的用户

解决方案

针对这个问题，Rspress 团队提出了以下解决方案：

1. 动态导入转换：将 require("lodash-es") 改为动态 import("lodash-es") 方式。

2. 异步函数适配：由于动态导入返回 Promise，相关函数需要改为异步函数。

3. 插件系统兼容性：确保 Rspress 插件系统能够支持异步钩子函数，以兼容修改后的异步 API。

实施建议

对于遇到类似问题的开发者，可以采取以下措施：

1. 检查依赖的模块格式：在使用第三方库时，注意查看其支持的模块系统。

2. 统一项目模块系统：尽可能保持项目中模块系统的一致性，要么全部使用 ESM，要么全部使用 CommonJS。

3. 构建工具配置：在构建工具中正确配置模块转换规则，特别是对于纯 ESM 包的处理。

总结

这个问题展示了在现代 JavaScript 生态系统中混合使用不同模块系统时可能遇到的挑战。Rspress 团队通过将同步 require 改为动态 import 的方式解决了这个问题，同时也确保了插件系统的向后兼容性。这为处理类似场景提供了一个很好的参考案例。

对于开发者而言，理解不同模块系统之间的差异以及构建工具如何处理这些差异，是构建稳定 JavaScript 应用的重要基础。