用了这么多年 Node.js 官方 API 文档，你大概早就习惯了那套朴素到有些复古的页面。
深色侧栏、密密麻麻的链接、几乎没有变化的布局。查一个陌生 API 时，很多人甚至不会先在文档里找，而是切回搜索引擎。
现在，Node.js 终于把这套文档重新做了一遍。
新版 API 文档已经开放 Beta 预览。最让人想说一句“早该有了”的功能也终于出现：站内搜索。
老文档确实该换了
Node.js 旧版 API 文档的优点很明确，轻、快、信息全。可它的界面也带着很强的时代痕迹，模块导航和正文挤在一张页面里，内容一长，定位信息就很费眼睛。
更麻烦的是，旧版一直没有内置搜索。想查 AbortSignal、AsyncLocalStorage 或某个命令行参数，要么靠浏览器页面搜索碰运气，要么先去 Google、Bing 等搜索引擎绕一圈。
对于一个拥有大量核心模块、版本跨度又很长的运行时来说，这种体验很难称得上顺手。
新版最先解决的就是“怎么更快找到东西”。
这次不只是换了一层皮
新版页面沿用了 nodejs.org 的设计体系，整体明显清爽了不少。左侧保留完整的模块导航，页面内目录也会持续显示，手机等小屏设备同样能够正常使用。
API 首页还把各模块的稳定性直接做成了表格。哪些是 Stable，哪些仍处于 Experimental，哪些已经 Deprecated，不用点进去就能看明白。
这次新增和保留的能力包括：
内置搜索：每个页面都能直接搜索 API，并提供键盘快捷方式。 统一导航：模块侧栏、页内目录和官网视觉体系放到了一起。 阅读体验优化：新增阅读时长、公告栏，并重新调整版式与信息层级。 常用功能没有丢：浅色与深色主题、ESM/CJS 切换、代码复制、稳定性标记、版本历史和 Markdown 页面都继续保留。 照顾特殊场景：关闭 JavaScript 或处于离线环境时，页面依然可以使用。
我最喜欢的还是搜索。界面变漂亮属于加分项，能不能在十几秒内定位到想要的 API，才决定一份文档是不是真的好用。
内容没变，底层生成工具换了
Node.js 官方强调，新旧文档的内容来源没有变化。新版依然读取 nodejs/node 仓库里的同一批 Markdown 文件，所以这不是另起炉灶重写文档，更不会出现两套内容各自更新的问题。
变化发生在生成和呈现环节。
新版由 Node.js 项目开发的独立工具 doc-kit 构建，用来替换此前的旧文档生成器。它不只负责生成新版网页，还能产出搜索所需的数据，以及面向 AI 工具的 llms.txt。
doc-kit 本身也是一个可以独立使用的开源项目。换句话说，这次重构留下的不只是一套 Node.js 官网页面，还有一套能够继续演进的 API 文档工具链。
llms.txt 可能比新界面更有后劲
新版文档还提供了 llms.txt。它把 Node.js API 文档整理成清晰的入口列表，让 AI 编程工具更容易发现并读取对应的 Markdown 内容。
这些入口会直接指向对应 API 的 Markdown 原文。相比让 AI 从导航、样式和脚本混在一起的网页中提取正文，这种结构更容易识别，也更适合作为检索和引用的资料来源。
这件事放在今天很实际。开发者正在用 AI 写越来越多的 Node.js 代码，但模型记忆里的 API 可能过时，也可能把实验性能力说成稳定功能。能否快速拿到当前版本的官方资料，会直接影响生成结果是否靠谱。
当然，llms.txt 不是让 AI 自动变准确的魔法。工具是否读取、如何引用以及能不能选对版本，仍然取决于具体实现。但官方主动提供结构化入口，至少让 AI 查文档不必再从复杂网页里盲目抓取。
先别急着告别旧版
目前新版仍是 Beta 预览，还没有替代默认 API 文档。Node.js 团队表示，重构已经进入最后阶段，但仍在收集真实使用中的问题和建议。
所以现在更适合把它当作一个可以提前体验的候选版本。搜索结果是否够准、长页面导航是否顺手、不同设备上的细节是否稳定，都需要继续打磨。
不过从目前的完成度来看，这次方向是对的。
Node.js API 文档过去不缺内容，缺的是一套符合今天使用习惯的入口。搜索、统一导航、移动端布局和 AI 友好的文档索引补齐之后，开发者终于不用在一张“能看，但不好找”的页面里来回翻了。
Node.js 这次重构来得有点晚，但总算没有继续让大家等下去。
