Node API 文档整容翻新,终于支持查找内容了!

👇 今日要闻

Hello 大家好，我是林语冰。

之前，Node 官网经过重新设计，UI 更加现代化了，但当时 Node 团队并没有顺便对 API 文档也同步翻新。

最近，Node 官网的文档按钮旁边出现了一个“beta Doc“链接，我偷看了 Node 的官方博客才知道，原来这是 Node 团队即将上线的 API 新文档。

Node 的 API 文档经过整容翻新，不仅沿袭了新官网的设计风格，而且更符合人体工程学，甚至 AI 也更易于访问。

今天我们就一起来瞄一下，Node 团队重做的 API 文档有哪些改良，这波“整容“是体验升级、还是审美降级。

👉 ESM 模块优先

CJS 是 Node 社区孵化并推动的服务端模块系统，而 ESM 则是 Ecma 国际组织官方上线的 JavaScript 标准模块系统。

简而言之，ESM vs CJS 模块的区别如下表所示：

由于 CJS 发源并根植于 Node 社区，Node 的 API 文档一直默认优先展示 CJS 模块的代码示例；另外，文档也提供了切换按钮，允许用户点击查看功能等价的 ESM 示例。

虽然但是，现代 JS 编程推荐 ESM 优先，比如 Pinia 等 npm 流行库都只支持纯 ESM 模块了。

因此，Node 新文档也与时俱进，提高了 ESM 模块的优先级。

举个栗子，setTimeout() API 的文档示例变动如下：

现在，Node 新/旧版文档均提供两种模块的代码示例，但新文档所有 API 示例默认都改用 ESM 模块。

如果你的项目仍在采用 CJS 模块，那么你也可以点击切换按钮，查看 CJS 的代码示例。

👉 UI 排版优化

Node 旧文档采用双列布局，左边侧边栏展示 Node 内置模块的目录列表，右边展示对应目录的主要内容。

这里的痛点在于，当你跳转到某个模块后，排版默认会在网页顶部把所有 API 超链接甩给你，乍看更像是一部信息量很大的英语词典......

更重要的是，虽然旧文档 API 五脏俱全，但却没有最常用的搜索功能。

我们搜索某个 API 往往需要反复横跳，不符合人体工程学，导致 Node 文档更像是一个“No dev“的开发无人区。

基本上，Node 旧文档几乎是一个零交互的静态网页，开发体验特别不好。“为此，新文档 首次 支持搜索功能，可以快捷搜索后快速跳转到指定 API。

此外，Node 团队优化了 API 文档的 UI，采用文档排版比较流行的三栏布局：

现在，Node 新文档新增右边侧栏，方便用户随时导航。

此外，Node 团队简化了 API 界面，默认隐藏不必要的信息，比如 API 具体的集成时间。

但是，API 相关的信息量却更大，如果用户想要溯源某个 API，可以查看其历史版本，包括新增时间和更新时间，甚至支持跳转到对应的 GitHub 资源。

还有，排版也进行了优化，API 的参数和返回值分离，用户一目了然。

我测评后发现，UI 新增了挺多细节，包括：

• 代码块支持行数显示
• 新增文档阅读时间
• 支持 llms.txt 以供 AI 参考

👉 TypeScript 友好

Node 新文档改用 TypeScript 风格的 API 签名，对前端开发者更加友好。

之前，Node 旧文档遵循 POSIX（可移植操作系统接口）风格，这源于古老的 Linux 操作系统手册的接口约定，在终端中很常见，比如 Vite CLI（命令行接口）和 git 命令的参数如下：

POSIX 文档的优点是与编程语言无关，有经验的开发者无阅读障碍。

优点也是缺点，很多新手对此一脸懵逼，赶上 AIGC 时代又不用阅读文档，就更“文盲“了。

Node 文档主要面向前端开发者，所以新文档改用了 TypeScript 风格的 API 签名。

举个栗子，setTimeout 的 API 签名变动如下：

可以看到，旧文档通过 [] 方括号表示可选参数，参数多了容易嵌套成“括号地狱“，人眼难以识别。

现在，新文档的可选参数改用 TypeScript 风格的 ? 问号表示，返回值也一目了然。TypeScript 用户直接享受母语级的阅读体验，anyScript 的语义懂得都懂，无需多言。

👇 重点总结

Node 团队翻新了 API 文档，我测评后发现新文档改良的若干细节：

• 设计对齐 Node 官网，排版优化，UI 简化
• 首次支持搜索功能，API 查询更快捷
• API 优先展示 ESM 示例，签名改用 TypeScript 风格
• 支持 llms.txt，方便 AI 工具访问文档

目前，Node 新文档已经开始公测，如果你测评新文档后有更好的建议或想要的功能，可以反馈给 Node 团队。

👉 你如何看待 Node API 文档整容后的用户体验改良？你更看好哪个 JS 运行时？或者你有任何其他有趣的想法和冷知识，欢迎在本文下方文明留言，友善交流。

👍 如果你读完本文有所收获，可以按赞打卡、在看推荐，甚至转发分享。

🙏 已经关注我的粉丝们，我们下期再见啦，掰掰~~

👇 参考文献：

• 🔗 Node 新文档：
  https://beta.docs.nodejs.org
• 🔗 Node 官方博客：
  https://nodejs.org/zh-cn/blog/announcements/new-api-docs-beta