鹏展博

外观

ofetch

约 491 字

NodeJS Browser Workers

概述

ofetch 是由 UnJS 团队开发的增强版 Fetch API 库，基于 TypeScript 实现，兼容 Node.js、浏览器和 Web Workers 环境。 它在原生 fetch 的基础上引入了 智能响应处理、错误自动抛出、请求拦截 等特性，同时保留了轻量级（约 4KB）和类型安全的优势。

特性

  • 智能响应解析：自动处理 JSON、文本、二进制等响应类型，无需手动调用 .json() 等方法
  • 全局拦截器：支持 onRequest、onResponse 和 onError 拦截器，用于统一添加请求头、处理错误或日志
  • 自动错误处理：非 2xx 响应状态码自动抛出错误，并附带结构化错误信息（如 error.data 和 error.status）
  • TypeScript 原生支持：提供完整的类型定义，支持请求/响应类型推断
  • 多环境兼容：在 Node.js 中基于 node-fetch-native 实现，浏览器端复用原生 Fetch API

安装

npm
npm install ofetch
pnpm
pnpm add ofetch
yarn
yarn add ofetch

使用

基础示例

import { ofetch } from 'ofetch'

// 自动解析 JSON 响应
const data = await ofetch('https://api.example.com/users')

// 处理二进制数据（如图片）
const imageBlob = await ofetch('/api/avatar', {
  responseType: 'blob'
})

全局配置与拦截器

const customFetch = ofetch.create({
  baseURL: 'https://api.example.com',
  headers: { Authorization: 'Bearer TOKEN' },
  timeout: 5000, // 5 秒超时
  retry: 2, // 自动重试次数
  onRequest({ options }) {
    // 请求前添加逻辑
    options.headers.set('X-Request-Source', 'browser')
  }
})

错误处理

try {
  await ofetch('https://api.example.com/invalid')
}
catch (error) {
  console.error(`Status: ${error.status}`) // 输出状态码（如 404）
  console.error(`Data: ${error.data}`) // 输出错误响应体
}

使用场景

  • Nuxt.js 应用：

    ofetch 是 Nuxt 的默认 HTTP 客户端（通过 $fetch）。可通过插件注入全局配置：

    // plugins/fetch.js
export default defineNuxtPlugin(() => {
  const { apiToken } = useRuntimeConfig().public
  globalThis.$fetch = ofetch.create({
    headers: { Authorization: `Bearer ${apiToken}` }
  })
})

  • 全栈 JavaScript 项目：

    在 Node.js 后端服务中替代 axios 或 node-fetch，实现前后端请求逻辑统一

  • 轻量级前端应用：

    对包体积敏感的项目，ofetch 的轻量化优势明显