Firebase Tools 项目中 Node.js v22+ 的 ESM 模块加载问题解析

问题背景

在 Firebase Tools 项目中使用 Node.js v22.12.0 及以上版本时，开发者遇到了一个关于 ESM 模块加载的特定问题。当项目配置为使用 ESM 模块（package.json 中设置 "type": "module"）并尝试部署 Firebase 函数时，系统会抛出 ERR_REQUIRE_ASYNC_MODULE 错误。

技术细节分析

这个问题的核心在于 Node.js v22.12.0 引入了一个重大变更：默认启用了 require(esm) 功能。这意味着 Node.js 现在允许通过传统的 require() 函数加载 ESM 模块。然而，当 ESM 模块中包含顶层 await 表达式时，这种加载方式就会失败。

在 Firebase Functions 的实现中，存在一个关键的 require() 调用，用于加载用户定义的函数模块。当这个模块是 ESM 格式且包含顶层 await 时，就会触发上述错误。

典型错误场景

开发者通常会遇到以下两种典型情况：

1. 部署时错误：当尝试部署包含顶层 await 的 ESM 模块到 Firebase Functions 时，部署过程会失败并显示 ERR_REQUIRE_ASYNC_MODULE 错误。

2. 本地模拟器问题：使用 firebase emulators:start 命令时，特别是带有 --inspect-functions 参数时，会出现相同的错误，导致函数无法正常初始化。

问题复现条件

要复现这个问题，需要满足以下条件：

• 使用 Node.js v22.12.0 或更高版本
• 项目配置为 ESM 模块（package.json 中包含 "type": "module"）
• 函数入口文件包含顶层 await 表达式
• 使用 Firebase Tools 进行部署或本地模拟

解决方案与替代方案

目前可行的解决方案包括：

1. 降级 Node.js 版本：暂时使用 Node.js v22.11.0 或更低版本可以避免此问题。

2. 重构代码结构：避免在模块顶层使用 await，将其移至异步函数内部。

3. 等待官方修复：关注 Firebase Tools 项目的更新，等待官方提供对 Node.js v22+ 的完整支持。

开发者注意事项

对于需要在项目中使用 ESM 模块和顶层 await 的开发者，建议：

• 仔细检查函数入口文件的模块导出方式
• 考虑将异步初始化逻辑封装到显式的初始化函数中
• 在 CI/CD 流程中固定 Node.js 版本以避免意外升级
• 关注 Firebase Tools 和 Node.js 的版本兼容性说明

技术展望

随着 Node.js 对 ESM 支持不断完善，预计 Firebase Tools 项目将很快提供对 Node.js v22+ 的完整支持。开发者可以期待未来版本中更流畅的 ESM 模块使用体验。

这个问题反映了 JavaScript 生态系统中模块系统过渡期的典型挑战，理解其背后的技术原理有助于开发者更好地应对类似问题。