大数跨境

注意,使用这个 API 可能导致你的 Node.js 出现兼容性问题!

注意,使用这个 API 可能导致你的 Node.js 出现兼容性问题! 前端Q
2024-11-05
0

大家好,我是 winty。

最近,Node.js 刚刚发布的 23 版本,我在前两天的文章里有具体介绍过:

Node.js 23 正式发布!

其中引入了一个比较重要的变化:允许通过 require() 引入 ESM 模块,这一变化极大地方便了开发者在使用 CommonJS 和 ESM 模块时的兼容性。

Node.js 23 最大的更新之一是现在可以默认使用 require() 引入原生的 ES 模块。在之前的版本(如 v20.x 和 v22.x)中,我们需要使用 --experimental-require-module 标志来开启这个功能,但在 v23.x 中,这个功能已经默认启用了。尽管如此,它仍处于实验阶段,我们期待用户反馈以便在完全稳定之前做出更多的微调。

但是,如果你的代码里使用了顶级 await,这可能会造成向后兼容性问题。

什么是顶级 await?

顶级 await 是指在模块的顶层作用域中直接使用 await 关键字进行异步操作,而无需将 await 关键字放置在异步函数内部。这一特性较大地简化了异步代码的编写,使得处理异步操作更加直观和简洁。

在过去,如果我们要在模块中使用异步操作,通常需要将其封装在一个异步函数中。例如:

// 过去的做法:需要一个异步函数来使用 await
async function main() {
    const data = await fetchData();
    console.log(data);
}

main().catch(console.error);

上面的代码中,我们需要定义一个 main 异步函数来包含 await,然后再调用这个函数并处理可能的错误。但这样的做法显得有些繁琐,尤其是在模块的顶层作用域中处理异步操作时。

而有了顶级 await,我们可以直接在模块的顶层作用域中使用 await 关键字。例如:

// 顶级 await 示例
const data = await fetchData();
console.log(data);

这种方式让代码更加简洁明了,并且避免了额外的函数定义和调用。

Node.js 23的新特性

在 Node.js 23 中,开发者可以通过 require() 直接加载使用 ESM (import/export) 的模块,而不再需要使用动态导入(dynamic import)。例如:

// 旧的动态导入方式
const theThing = await import('some/module/file.mjs');

这种方式需要使用 await,并且只能在异步函数中使用。而现在,可以直接使用 require():

// 新的导入方式
const theThing = require('some/module/file.mjs');

这种改变大大简化了模块的加载过程,也消除了大量的初始化逻辑。

使用顶级 await 带来的问题

然而,这种新的导入方式有一个重要的限制:如果模块中使用了顶级 await,则会引发错误 ERR_REQUIRE_ASYNC_MODULE。并且,这个错误不仅会出现在直接导入的文件,还可能出现在任何被导入文件所依赖的文件中,也就是说,如果你的项目或依赖项的任何部分使用了顶级 await,都可能导致这种错误。

向后兼容性问题

在引入顶级 await 之前,开发者可能不会把它视为重大版本更新(breaking change)。但是现在,如果你在项目中引入了顶级 await,使用 require() 的用户可能会因此出现错误,导致向后兼容性中断。

解决方案

对于这一问题,我们可以考虑以下几种解决方案:

  1. 不支持 require()
  • 明确告诉用户,如果他们使用 require(),需要自行解决相关问题。这要求用户阅读包的 README 文件,但很多用户可能不会注意到。
  1. 添加一个虚拟的 await
  • 如果你或你的依赖项未来可能会使用顶级 await,但目前还没有,可以在源代码中添加一个虚拟的 await ,例如:
    await "Good things come to those that support await";
  1. 明确破坏 CommonJS
  • 可以在 package.json 中通过 exports 键提供 CommonJS 和 ESM 支持,同时导出一个抛出错误的 CommonJS 文件,告知用户不应使用此包。

这些方案中,我个人比较倾向于第二种,因为如果将来 Node.js 支持在 CommonJS 文件中加载顶级 await 模块,这种方式会自动生效。

其他运行时的支持情况

  • Bun:在同一文件中可以混用 import 和 require,但使用 require() 导入顶级 await 模块仍会有同样的问题。
  • Deno:不支持 CommonJS,因此不存在此问题。

在模块中导入 CommonJS 文件与应对策略

导入 CommonJS 文件到 ESM 模块一直是可以的,通过标准的 import 语法即可实现。而且因为 CommonJS 不支持异步导出,所以在这种情况下不会存在顶级 await 引发的问题。

虽然本文大部分讨论的是对包维护者的影响,但实际上并不是每个包维护者都能处理好这类问题,因此作为用户你依然有可能暴露在这种问题之中。下面按优先级介绍几种应对策略:

  1. 停止使用 CommonJS,全面转向 ESM

这个问题只存在于使用 ESM 的 CommonJS 文件,而不是反过来。ESM 是未来的方向,继续使用 CommonJS 无疑是在使用一种即将被淘汰的技术。

  1. 为项目代码库配置测试

确保至少能够加载整个代码库。如果所有的(顶级的、非动态的)require() 都被执行和解析,任何依赖项的变化都会在你的 CI 环境和应用程序中立刻爆炸,及时发现问题。

  1. 检查你的依赖项是否仅支持 ESM

永远不要对这些 ESM-only 的依赖项使用 require()。这样可以保护你免受直接依赖项的问题。但请记住,即使你的直接依赖项是 CommonJS,这个问题仍可能在子依赖项中存在。

出于上述原因,我认为这样的变更不应被纳入稳定版本的 Node.js。其初衷是好的,但是却给开发者引入了新的困扰。

这样做实际上是将 JavaScript 的风格从 2 种扩展到了 3 种:

  1. CommonJS
  2. ESM
  3. ESM 但没有顶级 await

如果一个模块采用了第 3 种风格,它是兼容第 1 种风格的,但是如果依赖树的任何地方开始使用顶级 await,整个 ESM 依赖树就会从第 3 种风格变为第 2 种,从而破坏了与第 1 种风格的兼容性。

所以,还是希望大家能全面拥抱 ESM,这样就可以默认规避这些乱七八糟的问题了...


往期推荐


前端性能优化——如何对超大量数据进行渲染?
把大型项目(2.5k文件、30w+行代码)从 vite 前端迁移到了 rsbuild,收益如何?
Vue 竟然能实现这么多动画效果

最后


  • 欢迎加我微信,拉你进技术群,长期交流学习...

  • 欢迎关注「前端Q」,认真学前端,做个专业的技术人...

点个在看支持我吧

【声明】内容源于网络
0
0
前端Q
1234
内容 745
粉丝 0
前端Q 1234
总阅读0
粉丝0
内容745