ofetch

一个更好的 fetch API。适用于 Node.js、浏览器和 Web Workers。

预览

🚀 快速开始

安装：

# npm
npm i ofetch

# yarn
yarn add ofetch

导入：

// ESM / TypeScript
import { ofetch } from "ofetch";

// CommonJS
const { ofetch } = require("ofetch");

✔️ 支持 Node.js

我们使用条件导出来检测 Node.js 环境，并自动使用 unjs/node-fetch-native。如果 globalThis.fetch 可用，则会优先使用。要利用 Node.js 17.5.0 的实验性原生 fetch API，请使用 --experimental-fetch 标志。

keepAlive 支持

通过将 FETCH_KEEP_ALIVE 环境变量设置为 true，将注册一个 HTTP/HTTPS 代理，该代理会在没有未完成请求时保持套接字连接，以便将来的请求可以重复使用而无需重新建立 TCP 连接。

注意： 此选项可能会导致内存泄漏。请查看 node-fetch/node-fetch#1325。

✔️ 解析响应

ofetch 会使用 destr 智能解析 JSON 和原生值，如果解析失败则返回文本内容。

const { users } = await ofetch("/api/users");

对于二进制内容类型，ofetch 将返回一个 Blob 对象。

你可以选择提供一个不同于 destr 的解析器，或指定 blob、arrayBuffer 或 text 来强制使用相应的 FetchResponse 方法解析响应体。

// 使用 JSON.parse
await ofetch("/movie?lang=en", { parseResponse: JSON.parse });

// 原样返回文本
await ofetch("/movie?lang=en", { parseResponse: (txt) => txt });

// 获取响应的 blob 版本
await ofetch("/api/generate-image", { responseType: "blob" });

✔️ JSON 请求体

如果将对象或具有 .toJSON() 方法的类传递给 body 选项，ofetch 会自动将其字符串化。

ofetch 使用 JSON.stringify() 来转换传递的对象。没有 .toJSON() 方法的类必须提前转换为字符串值，然后再传递给 body 选项。

对于 PUT、PATCH 和 POST 请求方法，当设置了字符串或对象请求体时，ofetch 会添加默认的 content-type: "application/json" 和 accept: "application/json" 头部（你始终可以覆盖这些头部）。

此外，ofetch 支持 Buffer、ReadableStream、Stream 和兼容的请求体类型的二进制响应。ofetch 会自动设置 duplex: "half" 选项以支持流式传输！

示例：

const { users } = await ofetch("/api/users", {
  method: "POST",
  body: { some: "json" },
});

✔️ 错误处理

当 response.ok 为 false 时，ofetch 会自动抛出错误，并提供友好的错误消息和简洁的堆栈（隐藏内部细节）。

可以通过 error.data 获取解析后的错误主体。你也可以使用 FetchError 类型。

await ofetch("https://google.com/404");
// FetchError: [GET] "https://google/404": 404 Not Found
//     at async main (/project/playground.ts:4:3)

捕获错误响应：

await ofetch("/url").catch((error) => error.data);

要绕过状态错误捕获，可以设置 ignoreResponseError 选项：

await ofetch("/url", { ignoreResponseError: true });

✔️ 自动重试

如果发生错误且响应状态码包含在 retryStatusCodes 列表中，ofetch 会自动重试请求：

重试状态码：

• 408 - 请求超时
• 409 - 冲突
• 425 - 过早（实验性）
• 429 - 请求过多
• 500 - 内部服务器错误
• 502 - 网关错误
• 503 - 服务不可用
• 504 - 网关超时

你可以使用 retry 和 retryDelay 选项指定重试次数和重试间隔，也可以使用 retryStatusCodes 选项传递自定义状态码数组。

retry 的默认值为 1 次重试，但对于 POST、PUT、PATCH 和 DELETE 方法，ofetch 默认不重试，以避免引入副作用。如果你为 retry 设置了自定义值，它将对所有请求始终重试。

retryDelay 的默认值为 0 毫秒。

await ofetch("http://google.com/404", {
  retry: 3,
  retryDelay: 500, // 毫秒
});

✔️ 超时

你可以指定 timeout（以毫秒为单位）来在超时后自动中止请求（默认禁用）。

await ofetch("http://google.com/404", {
  timeout: 3000, // 3 秒后超时
});

✔️ 类型友好

响应可以进行类型辅助：

const article = await ofetch<Article>(`/api/article/${id}`);
// 可以自动补全 article.id

✔️ 添加 baseURL

通过使用 baseURL 选项，ofetch 会使用 ufo 为 baseURL 添加前导/后缀斜杠和查询参数：

await ofetch("/config", { baseURL });

✔️ 添加查询参数

通过使用 query 选项（或 params 作为别名），ofetch 会使用 ufo 将查询参数添加到 URL，同时保留请求本身的查询参数：

await ofetch("/movie?lang=en", { query: { id: 123 } });

✔️ 拦截器

可以提供异步拦截器来钩入 ofetch 调用的生命周期事件。

你可能想使用 ofetch.create 来设置共享拦截器。

onRequest({ request, options })

onRequest 在调用 ofetch 时立即被调用，允许你修改选项或进行简单的日志记录。

await ofetch("/api", {
  async onRequest({ request, options }) {
    // 记录请求
    console.log("[fetch request]", request, options);

    // 向查询参数添加 `?t=1640125211170`
    options.query = options.query || {};
    options.query.t = new Date();
  },
});

onRequestError({ request, options, error })

当 fetch 请求失败时，将调用 onRequestError。

await ofetch("/api", {
  async onRequestError({ request, options, error }) {
    // 记录错误
    console.log("[fetch request error]", request, error);
  },
});

onResponse({ request, options, response })

onResponse 将在 fetch 调用和解析响应体之后被调用。

await ofetch("/api", {
  async onResponse({ request, response, options }) {
    // 记录响应
    console.log("[fetch response]", request, response.status, response.body);
  },
});

onResponseError({ request, options, response })

onResponseError 与 onResponse 相同，但会在 fetch 发生但 response.ok 不为 true 时被调用。

await ofetch("/api", {
  async onResponseError({ request, response, options }) {
    // 记录错误
    console.log(
      "[fetch响应错误]",
      request,
      response.status,
      response.body
    );
  },
});

✔️ 使用默认选项创建fetch

如果你需要在多个fetch调用中使用通用选项，这个工具很有用。

注意： 默认值将在一个层级上被克隆和继承。请注意嵌套选项如headers。

const apiFetch = ofetch.create({ baseURL: "/api" });

apiFetch("/test"); // 等同于 ofetch('/test', { baseURL: '/api' })

💡 添加头部

通过使用headers选项，ofetch会在请求的默认头部之外添加额外的头部：

await ofetch("/movies", {
  headers: {
    Accept: "application/json",
    "Cache-Control": "no-cache",
  },
});

💡 添加HTTP(S) / 代理代理

如果你需要使用HTTP(S) / 代理代理，你可以（仅适用于Node.js）：

Node >= v18

使用undici的ProxyAgent添加到dispatcher选项

import { ofetch } from 'ofetch'
import { ProxyAgent } from 'undici'

await ofetch("/api", {
  dispatcher: new ProxyAgent("http://example.com"),
});

Node < v18

使用https-proxy-agent的HttpsProxyAgent添加到agent选项

import { HttpsProxyAgent } from "https-proxy-agent";

await ofetch("/api", {
  agent: new HttpsProxyAgent("http://example.com"),
});

🍣 访问原始响应

如果你需要访问原始响应（如获取头部等），可以使用ofetch.raw：

const response = await ofetch.raw("/sushi");

// response._data
// response.headers
// ...

原生fetch

作为快捷方式，你可以使用ofetch.native来获得原生fetch API

const json = await ofetch.native("/sushi").then((r) => r.json());

📦 打包工具注意事项

• 所有目标都以模块和CommonJS格式导出，并使用命名导出
• 为了保持现代语法，没有对任何导出进行转译
  • 你可能需要使用Babel转译ofetch、destr和ufo包以支持ES5
• 你需要为fetch全局变量提供polyfill以支持旧版浏览器，比如使用unfetch

❓ 常见问题

为什么导出被称为ofetch而不是fetch？

使用与fetch相同的名称可能会造成混淆，因为API不同，但它仍然是一个fetch，所以使用最接近的可能替代方案。然而，你可以从ofetch中导入{ fetch }，它在Node.js中是自动polyfill的，而在其他环境中使用原生fetch。

为什么没有默认导出？

默认导出总是有与CommonJS导出混淆的风险。

这也保证我们可以引入更多工具而不破坏包，同时也鼓励使用ofetch名称。

为什么不进行转译？

通过转译库，我们会用不必要的遗留代码推动Web倒退，这对大多数用户来说是不需要的。

如果你需要支持旧版用户，你可以选择在你的构建流程中转译这个库。

许可证

MIT。用💖制作