ofetch
约 491 字大约 2 分钟
2024-09-12
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 的轻量化优势明显