由 Sindre Sorhus 开发、基于 Fetch API 的轻量级 JavaScript HTTP 客户端 Ky，近日发布了 2.0 版本。这是该项目多年来首次发布大版本更新，带来了重构后的 Hook 系统、更完善的超时控制、更清晰的 URL 处理方式，以及内置的响应数据校验能力。

Ky 2.0 最大的变化之一是对 Hooks API 的统一。此前，beforeRequest、afterResponse、beforeRetry 和 beforeError 等 Hook 分别接收不同参数，而现在它们全部改为接收统一的状态对象： {request, options, retryCount, ...} 。这种设计让整个 Hook 体系变得更加一致，也为未来继续扩展接口留下了空间。与此同时，新版本新增了一个 init Hook，它会在所有其他 Hook 之前执行。此外，beforeError 现在不再只处理 HTTPError，而是会在所有错误类型发生时触发。

超时机制也是此次更新的重点。除了原本针对单次请求尝试的 timeout 超时控制外，Ky 2.0 新增了 totalTimeout 选项，用于限制整个请求生命周期的总耗时，包括重试和等待时间在内。一旦超过这个时间限制，就会抛出 TimeoutError。重试机制也进行了调整。Ky 引入了新的 NetworkError 类型，并将自动重试的范围限制在真正的网络故障上，例如 DNS 解析失败或连接被拒绝等情况，而不会再因为程序错误或其他非网络异常而触发重试。

长期以来容易让用户困惑的 URL 处理逻辑，在 2.0 中也进行了重新设计。原来的 prefixUrl 被更名为 prefix，并允许请求路径以斜杠开头；同时新增了 baseUrl 配置，用于按照标准 URL 解析规则拼接地址。两种用法的职责被明确区分，避免了此前一些容易踩坑的行为。

响应数据处理方面，Ky 2.0 为 .json() 方法加入了 Standard Schema 校验支持。开发者可以直接结合 Zod、Valibot 等兼容的验证库，对接口返回数据进行运行时校验，同时获得完整的 TypeScript 类型推导能力。另外，HTTPError 现在新增了已经解析好的 data 属性。过去如果想读取错误响应体，通常需要再次调用 error.response.json()，既麻烦又可能导致资源释放问题。现在错误数据会提前完成解析，开发者可以直接通过 error.data 获取。

在 Hacker News 上，维护者 Seth Holladay 这样总结此次更新：

这次加入了很多提升开发体验的改进。超时机制和 Hook 系统都进行了重构，自定义实例中的 Base URL 问题也终于解决了。我们修复了目前已知的所有问题。

当被问到 Ky 与 Axios 的区别时，他表示：

Ky 从一开始就是围绕 Fetch 设计的，而 Axios 是后来尝试适配 Fetch，这种适配并不总是理想。与此同时，Ky 的 TypeScript 支持也更完善，包括内置的 Schema 校验和类型推导能力。

Reddit 上不少开发者也对新版本给予了积极评价。一位用户表示：

这个项目挺酷的，可以理解成 fetch 升级版。这里面的大部分功能其实都是我自己封装 fetch 时会写的东西，但自己维护这些封装很麻烦，而且还得写一堆测试。

另一位从 Axios 转向 Ky 的开发者则表示自己“非常喜欢”这个库，还有人认为 2.0 中新增的这些改动都非常实用。

当然，大版本升级也意味着一些不兼容变更。Ky 2.0 现在要求 Node.js 22 及以上版本；所有 Hook 回调都必须迁移到新的状态对象形式；.json() 在遇到空响应或 204 响应时会抛出异常，而不再返回空字符串；searchParams 会与 URL 中已有的查询参数进行合并；错误响应体也需要从 error.data 中读取，而不是继续调用 error.response.json()。官方发布说明同时提供了完整的迁移指南，并给出了每项变更的前后对比示例。

Ky 是一个开源 HTTP 客户端项目，目前由 Sindre Sorhus、Seth Holladay 和 Szymon Marczak 共同维护。整个库仅有几 KB 大小，同时支持浏览器、Node.js、Bun 和 Deno 环境。它将自己定位为一个更加轻量、更加贴近 Fetch 原生设计的 Axios 替代方案。

查看英文原文：Ky 2.0 Fetch API Wrapper with Revamped Hooks, Smarter Timeouts, and Built-In Schema Validation - InfoQ