不用先装什么框架也不用引入第三方库浏览器自带的fetch就直接把接口调用这件事做到了足够优雅。我最早是从 jQuery 的$.ajax开始写前后端联调的后来切到 axios再后来项目里逐步把请求层换成了原生fetch。这一路下来有个很明显的感觉fetch不是简单地把XMLHttpRequest换个写法它在设计思路上就完全不一样。这篇内容我想把fetch方法、请求参数、实际项目里的用法和一些踩坑经验整理出来适合刚接触接口调用的前端新手也适合想从 axios 迁移到原生请求方案的同学参考。1. Fetch 到底是什么——从 Ajax 到 Fetch 的演进1.1 为什么前端需要统一的接口调用方案前端开发几乎离不开接口调用。页面上展示的用户信息、提交表单数据、上传文件、加载更多列表背后都是一次次 HTTP 请求。早些年大家用XMLHttpRequest写请求代码啰嗦不说回调嵌套一多读起来真的很痛苦。后来 jQuery 封装了$.ajax用起来舒服了一些但 jQuery 本身是个重型 DOM 操作库为了一个请求方法引入整个库在现在的工程化项目里显得不太划算。axios 解决了 Promise 化的问题也支持拦截器、取消请求这些高级能力直到今天仍然是很多项目的首选。但浏览器原生提供的fetchAPI 从 Chrome 42 开始就已经可用到现在所有主流浏览器都支持得非常好。它和XMLHttpRequest最大的区别是fetch基于 Promise天然支持async/await代码写起来更像同步逻辑可读性提升非常明显。1.2 Fetch 和 XMLHttpRequest 的核心差异XMLHttpRequest的交互模型是事件驱动的你要手动监听onreadystatechange或者onload事件还要手动判断readyState和status来确认请求是否成功。fetch就简单直接它接收一个 URL 和一个配置对象返回一个 Promise通过response.ok判断请求是否成功通过response.json()、response.text()这些方法解析响应体。从编程体验来说fetch更符合现代 JavaScript 的开发习惯。而且它被设计成底层能力所以不光能请求 HTTP 接口还可以配合 Service Worker 做离线缓存、配合流式读取处理大文件响应。这一点是XMLHttpRequest比较难做到的。1.3 Fetch 兼容性和适用场景fetch的兼容性在 2024 年已经不用太担心。所有现代浏览器Chrome、Firefox、Safari、Edge都原生支持移动端 WebView 只要系统版本不是特别老也都能用。如果项目需要兼容 IE 或者非常老旧的 WebView那还是得用 axios 或者 polyfill。适用场景上fetch特别适合这几类项目使用原生 JavaScript 或简单框架的前端工程不想引入额外请求库Node.js 18 环境下写服务端脚本因为 Node 从 18 开始原生支持全局fetch云函数、Serverless 函数里调用第三方 HTTP 接口学习和理解 HTTP 请求本质的入门场景2. Fetch 方法签名和请求参数完整拆解2.1 基本语法和参数说明fetch的完整签名是这样fetch(resource, options)第一个参数resource是必填的可以是 URL 字符串也可以是一个Request对象。第二个参数options是可选的配置对象用来控制请求方法、请求头、请求体、缓存策略、凭证模式等等。最简单的 GET 请求只需要传 URLfetch(https://api.example.com/users) .then(response response.json()) .then(data console.log(data))这个请求默认使用 GET 方法默认带上同源的 Cookie但不会带跨域的 Cookie。这里面的细节后面会展开讲。2.2 options 对象里的常用请求参数options对象是整个fetch的核心掌握它基本就掌握了接口调用的大半。参数类型默认值说明methodstringGETHTTP 请求方法常用 GET、POST、PUT、DELETE、PATCHheadersobject{}请求头比如Content-Type、Authorizationbodystring / FormData / Blob / URLSearchParams无请求体GET 和 HEAD 请求不能带modestringcors请求模式cors、no-cors、same-origin等credentialsstringsame-origin是否携带 Cookieomit、same-origin、includecachestringdefault缓存模式default、no-store、reload、force-cacheredirectstringfollow重定向处理follow、error、manualsignalAbortSignal无用于取消请求配合AbortController使用headers是最常用的一个参数。设置 JSON 请求体的类型时通常会这样写fetch(https://api.example.com/users, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ name: 张三, age: 18 }) })注意body传对象之前要先JSON.stringify直接用对象会报错。这是新手最容易踩的坑之一。2.3 GET 请求传参的三种方式GET 请求不能带 body所以参数只能放在 URL 上。常见的有三种写法第一种直接拼接字符串fetch(https://api.example.com/users?page1pageSize20)第二种用URLSearchParams构造查询参数const params new URLSearchParams({ page: 1, pageSize: 20, keyword: 张三 }) fetch(https://api.example.com/users?${params.toString()})第三种用URL对象设置const url new URL(https://api.example.com/users) url.searchParams.set(page, 1) url.searchParams.set(pageSize, 20) fetch(url)我推荐优先使用URL对象的方式。因为URLSearchParams自动处理编码比如中文关键字会编码成%E5%BC%A0%E4%B8%89这种格式避免因为特殊字符导致接口解析错误。3. 请求头配置和请求体构造——联调中的关键细节3.1 Content-Type 的三种常见形式Content-Type是联调时最常碰到的请求头它告诉服务端请求体是什么格式。三种常见形式对应三种不同的传参方式。第一种application/json。这是前后端分离项目里最常用的格式适合传结构化对象。服务端用RequestBody或者类似注解接收fetch(https://api.example.com/users, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ name: 李四, email: lisiexample.com }) })第二种application/x-www-form-urlencoded。这种格式适合传简单的键值对body 需要写成key1value1key2value2的形式用URLSearchParams可以方便地生成fetch(https://api.example.com/login, { method: POST, headers: { Content-Type: application/x-www-form-urlencoded }, body: new URLSearchParams({ username: admin, password: 123456 }) })第三种multipart/form-data。这种格式专门用来传文件或混合表单数据。关键点在于用FormData对象传给 body 时不要手动设置 Content-Type浏览器会自动加上带 boundary 的完整请求头const formData new FormData() formData.append(file, fileInput.files[0]) formData.append(description, 这是文件描述) fetch(https://api.example.com/upload, { method: POST, body: formData })如果手动设置了Content-Type: multipart/form-data反而会导致请求失败因为缺少了自动生成的 boundary 分隔符服务端就没法正确解析上传的内容。3.2 Headers 对象和常见鉴权配置除了Content-Type另一个高频请求头就是Authorization用来传递 Token。在实际项目中Token 通常是登录成功后存在本地存储里的const token localStorage.getItem(token) fetch(https://api.example.com/user/profile, { method: GET, headers: { Authorization: Bearer ${token} } })headers参数除了用纯对象还可以用Headers这个 API 来构造。用Headers对象的好处是可以方便地追加、删除请求头也可以直接用has()、get()来检查const headers new Headers() headers.append(Content-Type, application/json) headers.append(Authorization, Bearer ${token}) fetch(https://api.example.com/user/profile, { method: POST, headers: headers, body: JSON.stringify({}) })关于 Token 存储我想多说一句。很多教程喜欢把 Token 放在localStorage虽然够用但安全性一般XSS 攻击能直接读走。更稳妥的做法是放到HttpOnly的 Cookie 里配合请求时用credentials: include让浏览器自动携带。这个不在 fetch 的讨论范围内但和接口调用密切相关选型的时候要考虑清楚。3.3 请求体序列化的常见坑JSON 序列化看起来简单但实际操作中还是有几个坑值得注意。第一个坑是日期格式。JavaScript 的JSON.stringify会把Date对象转成 ISO 字符串形如2024-06-01T08:30:00.000Z。这个格式在大多数后端框架里都能解析但如果后端用的反序列化库不认这个格式就可能会报错。稳妥的方案是在序列化之前先把日期格式化成后端需要的格式比如2024-06-01 08:30:00。第二个坑是数字精度。如果接口需要传超过 JavaScript 安全整数范围Number.MAX_SAFE_INTEGER的 ID比如某些雪花算法生成的 ID 是 19 位数字直接 JSON 序列化会导致精度丢失。这种情况建议和后端约定用字符串传 ID或者单独处理序列化逻辑。第三个坑是空值处理。有些后端严格区分null和undefined而JSON.stringify会把值为undefined的属性直接忽略掉。如果接口要求某些字段即使为空也必须出现在 JSON 里那前端要把这些字段的值设为null而不是undefined。4. 响应处理和异常捕获——理解 fetch 与其他库的关键区别4.1 fetch 只在网络层失败时 reject使用fetch时我最想强调的一点是只有当网络请求本身失败时fetch 返回的 Promise 才会 reject。什么情况算网络层失败呢服务器没开、DNS 解析失败、CORS 被拦截、断网了这些会 reject。但是 HTTP 状态码是 404、500、502 这种fetch 不认为这是失败Promise 照样 resolve。这就导致了一个问题如果不做额外判断接口返回 500 的时候前端拿到的是response.ok false的响应而不会走进catch分支。很多新手会疑惑为什么后端明明报错了前端catch里却没捕获到。所以处理响应时首先要判断response.okfetch(https://api.example.com/users) .then(response { if (!response.ok) { throw new Error(HTTP error! status: ${response.status}) } return response.json() }) .then(data { console.log(请求成功, data) }) .catch(error { console.log(请求失败, error) })配合async/await写法会更清晰async function getUsers() { try { const response await fetch(https://api.example.com/users) if (!response.ok) { throw new Error(HTTP error! status: ${response.status}) } const data await response.json() return data } catch (error) { console.log(请求异常, error) throw error } }还有个细节值得注意response.ok只判断状态码在 200-299 范围内如果后端在 200 响应体里返回业务错误码比如{ code: 500, message: 业务失败 }response.ok判断不出来。这种情况需要在业务层额外处理const data await response.json() if (data.code ! 0) { throw new Error(data.message || 业务处理失败) }这样可以统一走异常处理逻辑。具体字段叫什么是code还是status要看后端返回的格式约定。4.2 response 对象的常用方法和注意事项fetch返回的Response对象有几个常用的解析方法方法用途注意事项response.json()解析 JSON 响应体不是合法 JSON 时报错response.text()解析文本响应体适合 HTML、纯文本response.blob()解析二进制数据适合图片、文件下载response.formData()解析表单数据实际项目用得少response.arrayBuffer()解析 ArrayBuffer适合需要操作原始字节流的场景这些方法都返回 Promise而且都是异步执行的。有个坑是Response 对象的 body 只能被读取一次。你调用了response.json()之后再调用response.text()拿不到原始内容了会报错。所以判断响应格式时要提前决定用哪个方法不要先试试text()再试json()这种思路。需要了解响应头信息比如分页接口的总条数时可以通过response.headers.get(X-Total-Count)这种方式读取。跨域请求默认只能读取一部分简单响应头自定义响应头需要后端在 CORS 配置里暴露Access-Control-Expose-Headers才能读到。4.3 HTTP 状态码处理的完整思路实际项目里合理的响应处理策略是按状态码区间和业务状态分层处理2xx请求成功正常解析数据401未认证或 Token 过期跳转登录页403无权限提示用户或做权限引导404接口不存在检查 URL 路径5xx服务端异常提示“系统繁忙”并提供重试入口async function request(url, options {}) { try { const response await fetch(url, options) if (response.status 401) { // Token 过期清除本地登录态并跳转登录页 localStorage.removeItem(token) window.location.href /login throw new Error(登录状态已过期请重新登录) } if (response.status 403) { throw new Error(没有权限执行此操作) } if (!response.ok) { throw new Error(请求失败状态码${response.status}) } return await response.json() } catch (error) { if (error.name AbortError) { console.log(请求已取消) return null } throw error } }这里把取消请求也考虑进去了因为AbortError在 signal 触发时会被 fetch 抛出来拦截它避免把取消当成真正的异常上报。5. 实战案例封装一个支持超时和取消的请求函数5.1 用 AbortController 实现超时控制和手动取消fetch原生不支持超时设置这和 axios 不太一样。axios 有timeout配置fetch没有。不过可以用AbortController和setTimeout配合来实现超时功能。基本思路是创建一个AbortController把它的signal传给 fetch 的 options。超时或需要取消时调用controller.abort()fetch 就会中断请求并抛出一个名为AbortError的异常。function fetchWithTimeout(url, options {}, timeout 10000) { const controller new AbortController() const { signal } controller const timer setTimeout(() { controller.abort() }, timeout) return fetch(url, { ...options, signal }) .finally(() clearTimeout(timer)) }这样调用的时候超过 10 秒还没有响应请求就会自动取消并且抛出的错误可以通过error.name AbortError来识别。5.2 封装统一的请求方法处理 JSON、文件上传和错误提示在实际项目中直接在每个页面写fetch调用会有大量重复代码。更合理的做法是统一封装一个请求方法然后在内部处理 Header 注入、错误提示、业务状态码判断这些通用逻辑。下面是一套比较基础的封装思路可以在项目里直接改造使用async function request(url, options {}) { const token localStorage.getItem(token) const defaultHeaders { Content-Type: application/json, ...(token ? { Authorization: Bearer ${token} } : {}) } const controller new AbortController() const timer setTimeout(() controller.abort(), 10000) try { const response await fetch(url, { ...options, headers: { ...defaultHeaders, ...(options.headers || {}) }, signal: controller.signal }) if (response.status 401) { localStorage.removeItem(token) window.location.href /login throw new Error(登录已过期) } if (!response.ok) { throw new Error(请求失败${response.status}) } const data await response.json() if (data.code ! 0) { throw new Error(data.message || 服务器返回错误) } return data.data } catch (error) { if (error.name AbortError) { throw new Error(请求超时请稍后重试) } throw error } finally { clearTimeout(timer) } }这个封装有几个设计点Header 默认注入 JSON 类型和 Token但允许调用方覆盖自动处理登录过期逻辑统一判断 HTTP 状态和业务状态码所有异常统一以Error形式抛出调用方用try/catch接收即可5.3 文件上传时封装要注意什么文件上传时不能用默认的Content-Type: application/json要特殊处理。我在封装里通常不设置默认 Content-Type而是让每个请求自己决定或者在上传场景明确不设置async function uploadFile(url, file, extraData {}) { const formData new FormData() formData.append(file, file) Object.entries(extraData).forEach(([key, value]) { formData.append(key, value) }) const response await fetch(url, { method: POST, headers: { // 不要设置 Content-Type让浏览器自动生成 // Authorization 仍然要带 Authorization: Bearer ${localStorage.getItem(token)} }, body: formData }) if (!response.ok) { throw new Error(上传失败${response.status}) } return response.json() }这里的核心点还是那一个FormData场景千万别手动设置Content-Type否则 boundary 缺失会导致上传失败。这个坑我在刚用fetch时就踩过一次排查半天发现请求头被框架统一设置了最后通过在封装里区分处理才解决。6. 常见问题排查和避坑经验6.1 Failed to fetch 到底是什么意思“Failed to fetch”是fetch请求失败时浏览器报的通用错误信息。它的含义很宽泛可能的原因包括服务器没启动或地址写错服务器宕机或端口不通DNS 解析失败CORS 跨域被浏览器拦截请求被防火墙拦截HTTP 协议和 HTTPS 协议混用导致浏览器阻止请求离线或断网排查这个错误时先打开开发者工具的 Network 面板看请求有没有发出去。如果请求显示红色且没有响应体多半是网络层或 CORS 问题。如果请求有响应但前端报错那要看是不是解析响应时出了问题。这里有一个容易混淆的点很多项目的热词里会出现“pdf.js failed to fetch”“git fetch failed”这类信息。它们虽然也带“fetch”这个词但跟前端浏览器的 fetch API 根本不是一回事。pdf.js 的 failed to fetch 是 PDF 文件资源加载失败git 的 fetch 是拉取远程仓库内容失败。做前端接口调试时要先确认报错来源于自己的代码还是第三方库。6.2 403 状态码的常见原因和处理思路热词里出现了fetch remote profile with status 403这种场景。403 表示服务器理解请求但拒绝执行。在接口对接中403 常见的触发原因有Token 无效、过期或者压根没传用户权限不足比如普通用户访问了管理员接口接口做了 IP 白名单限制请求头里缺少必要的鉴权信息比如某些服务要求额外传X-Api-Key排查 403 时第一步检查请求头里 Authorization 是否正确地传了第二步看 Token 是否过期第三步和后端确认当前账号是否拥有该接口的权限。如果是服务端到服务端的调用还要检查 API 密钥是否已经配置在环境变量里而不是硬编码在代码中。6.3 接口调用中关于 API 密钥权限的理解随着 AI 接口和大模型服务的普及关于 API 密钥API Key的问题越来越多。我看到有讨论说“豆包如何调用 api 接口”“体验 servlet 调用大模型 api 接口”这些场景里 API 密钥的管理是一个绕不开的话题。前端调用任何需要鉴权的外部服务时API 密钥都不能直接暴露在浏览器端。浏览器里的 JS 代码任何人打开开发者工具都能看到把密钥硬编码进去等于把钥匙挂在门口。正确做法是把密钥保存在后端服务器环境变量里由后端代理转发请求前端请求自己的后端接口再由后端携带密钥去调用第三方服务。按照这个原则来理解 fetch 中的鉴权头如果是登录后拿到的用户 Token前端保存并在每次请求中携带是合理的如果是你自己在某个开放平台申请的 API 密钥那它就应该只出现在服务端代码里。6.4 请求缓存问题导致的数据不更新fetch默认走浏览器 HTTP 缓存策略如果接口响应头里有Cache-Control或ETag相关配置浏览器可能会直接返回缓存的旧数据导致页面上数据看起来“没更新”。这在排查接口问题时是一个容易被忽略的点。处理方案有几种在请求 URL 后面加随机参数或时间戳fetch(https://api.example.com/data?_t${Date.now()})在 fetch options 里设置cache: no-storefetch(https://api.example.com/data, { cache: no-store })由后端在响应头里加Cache-Control: no-cache实际项目里方案 1 最常用也最简单。方案 2 适合全局设置但要注意某些代理层可能不完全遵守这个配置。7. Fetch 在 AI 接口调用中的实践7.1 大模型 API 调用中 Fetch 能做什么最近大家讨论“豆包如何调用 api 接口”这类问题时会发现很多大模型服务商都提供 HTTP 接口。虽然官方通常给出 Python 或 Node.js 的 SDK但在前端页面里直接调用时fetch就是最直接的方案。尤其是做 AI 应用原型、个人工具或内部分享的 Demo 时用fetch调大模型接口非常方便。常见的调用方式是 POST 一个 JSON 请求体带上模型名称、消息列表和参数。比如const response await fetch(https://api.example.com/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey} }, body: JSON.stringify({ model: gpt-3.5-turbo, messages: [ { role: user, content: 你好请介绍一下自己 } ], temperature: 0.7 }) }) const data await response.json() console.log(data.choices[0].message.content)这个例子里fetch承担了向 AI 服务商发送请求、接收流式响应的任务。大模型接口相比普通业务接口有一些特殊的处理逻辑比如流式输出、长连接、Token 计费这些都和fetch的使用方式直接相关。7.2 流式响应在处理和取消控制上的注意事项大模型接口常见的响应方式是流式输出SSEServer-Sent Events也就是后端不是一次性返回完整结果而是像打字机一样一段一段地返回内容。fetch能比较优雅地处理这种情况因为response.body本身就是一个可读流ReadableStream。读取流式响应时使用response.body.getReader()配合TextDecoderconst response await fetch(https://api.example.com/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey} }, body: JSON.stringify({ model: gpt-3.5-turbo, messages: [{ role: user, content: 写一首诗 }], stream: true }) }) const reader response.body.getReader() const decoder new TextDecoder() let content while (true) { const { done, value } await reader.read() if (done) break content decoder.decode(value, { stream: true }) // 这里可以更新页面上的文本内容实现打字机效果 console.log(当前内容, content) }这种流式处理的场景fetch比 axios 更顺手因为 axios 默认会把完整响应体先缓存下来处理流式时需要额外配置。AI 接口调用比较常见的“取消生成”按钮也可以通过前面讲到的AbortController实现——用户点击停止时调用controller.abort()中断流式读取同时避免浪费 Token 消耗。7.3 AI 接口调用中关于 API 密钥权限和算力的提醒前面提到 API 密钥和算力的问题我觉得有必要再具体展开一下。AI 服务商的接口通常是按 Token 计费的这意味着每次调用都在消耗算力成本。如果把 API 密钥暴露在浏览器端别人可以直接盗用你的密钥去调用付费接口造成经济损失。这类事情并不少见。所以凡是涉及 AI 大模型接口的前端项目我都建议做一层后端代理前端请求你自己服务器的接口服务器端保存真正的 API 密钥由服务器去请求 AI 服务商。这样前端拿到的只是你自己接口的地址密钥不会暴露。这也是目前绝大多数生产级 AI 应用的实际架构。在开发调试阶段很多人会图方便直接用前端fetch去请求 AI 接口并带上密钥。我这里给一个比较明确的操作原则本地开发、个人 Demo、仅供自己使用的小工具如果密钥只存在你自己电脑环境变量里且不提交到仓库勉强能接受但只要项目要部署、要给别人看、要上生产密钥就必须迁移到后端。你也不想某天打开后台看到几千块莫名其妙的账单吧8. 关于 Fetch 与其他请求方案的选型思考8.1 Fetch 和 axios 怎么选做项目选型时fetch和 axios 之间常被拿来对比。我自己的实践是小项目、原生前端、Node 脚本用fetch完全够用大型项目、复杂拦截器需求多、要兼容旧浏览器的工程axios 的生态更成熟。axios 的优势在于内置超时、拦截器、取消请求、自动转换 JSON、防御 CSRF 等能力开箱即用。fetch的优势在于原生支持、体积为零、Promise 风格、配合 Service Worker 做离线可用性好。两者不是非此即彼的关系同一个项目里混合使用也是很常见的事。如果团队用的框架是 Vue 3 或 React配一个基于fetch封装的轻量请求层完全能替代 axios 的日常功能。而且对追求页面加载速度和依赖体积的团队来说少一个第三方请求库能省掉不少资源。8.2 Node.js 环境下的 FetchNode.js 从 18 版本开始把fetch作为全局 API 提供不需要安装node-fetch包。这意味着写服务端脚本、写爬虫、写自动化任务时也可以统一用fetch发请求语法和浏览器端完全一致。不过 Node 环境的fetch是基于undici实现的和浏览器的实现有些细微差异。比如 Node 端默认不携带 Cookie、不处理缓存等但这些对服务端脚本调用接口影响很小。如果脚本需要设置超时时间逻辑和浏览器端一样用AbortController处理即可。8.3 API 密钥权限管理与安全边界接口调用久了会逐渐形成一个认知请求能不能通取决于接口地址、请求参数、鉴权信息三个要素。接口地址是终点请求参数是内容鉴权信息是准入凭证。搞丢任何一个调用都会失败。而鉴权信息的权限管理是接口调用中最不能偷懒的部分。体现在fetch的实际使用中就是把 API 密钥、App Secret 这类私密信息放在安全的地方服务端环境变量绝不硬编码到前端代码里。另外请求日志里也要注意不要把包含完整鉴权头的请求信息打出来避免敏感信息泄露。9. 对接口调用的整体心得我在文章最后想聊几点个人体会。fetch这个 API 看起来简单要真正用好需要理解 HTTP 请求的本质——方法、URL、请求头、请求体、响应状态、响应体不管用什么库最终都是围绕这几个要素做文章。熟练了fetch再去用 axios 或者其他封装库会发现它们只是在不同层面帮你省了一些代码量核心逻辑完全相通。另外接口联调时一定要学会看浏览器的 Network 面板。很多前端报错其实不是代码问题而是请求头少了、参数格式不对、后端跨域没配置。拿着 Network 面板的信息和后端同学沟通效率会高很多。最后想提醒一点动手实践时建议直接在浏览器控制台里跑几个fetch示例观察response.ok、status、headers这些属性在不同情况下的表现。接口调用这件事光看文档不够多跑几次真实请求很多疑惑会自然解开。
