深入理解Fetch API：Request、Response与Body混入全解析

写这篇东西的起因很简单我发现自己团队里的前端新人用 fetch 好几个月问起来Request 对象是啥Response 和 fetch 返回的那个玩意有啥区别Body 混入又是什么全是一脸懵。这其实不怪他们市面上 90% 的教程都只教fetch(url).then(res res.json())这一句把 Fetch API 背后真正的设计逻辑完全糊弄过去了。但你要是真写过复杂的上传、下载、Service Worker 离线缓存、或者要对接一个动不动返回各种状态码的老接口你会发现不理解 Request、Response、Body 混入这三兄弟你连报错都看不懂。这篇文章我打算把这三块一次性讲透先拆 Request 和 Response 对象到底是什么再重点啃 Body 混入这个最容易被忽略、却决定你能不能拿到数据的关键机制。每个部分都会配可复现的代码和实际案例分析最后会把日常项目里高频出现的几个报错比如 failed to fetch、request header is too large、429 限流一次性说清楚。适合刚入门但想搞明白原理的初级开发者也适合天天用 fetch 但停留在会用层面的中高级开发者查漏补缺。1. 先搞清楚 Fetch API 的底子Request 和 Response 到底扮演什么角色1.1 用快递流程理解三者的分工如果你想把 Fetch API 一次讲明白我建议直接用快递来打比方。你要寄一个包裹需要填一张快递单上面写着寄给谁、走什么快递、包裹多重、要不要保价——这就是Request 对象。快递公司送完货给你一张回执单上面写着签收人、签收时间、包裹状态——这就是Response 对象。而包裹本身里面那件货就是body。Body 混入Body mixin则是一套开箱规则它规定了你用什么姿势拆快递徒手撕是text()用开箱器是json()怕损坏要拍照留证是blob()要把包裹整个塞进仓库归档是arrayBuffer()。这个类比不是随便打的。Fetch API 从设计之初就不是发个请求拿个结果这么简单的一锤子买卖它被寄予厚望要支撑 Service Worker、流式传输、网络代理这些高阶场景。所以它把一次 HTTP 通信抽象成了两个可独立存在、可随意传递、可反复克隆的实体——Request请求和 Response响应。你在fetch()里传的那个字符串其实只是创建 Request 对象的语法糖你拿到的那个 Promise 最终 resolve 出来的就是一个实打实的 Response 对象。1.2 为什么非要把它们单独拆出来这里必须说一个很多教程没讲透的点fetch()的入参和返回值本质上是 Request 和 Response 的实例。这意味着它们可以被单独创建、保存、传递和复用。举个例子你在页面里要发出 10 个几乎一样的 POST 请求只是 body 不同。如果每次都用字符串就得重复写 10 遍 method、headers、credentials。但如果你先const baseRequest new Request(/api/upload, { method: POST, headers: {...} })后面 10 次请求都能基于它 clone 或者直接复用代码会清爽得多。更关键的场景在 Service Worker。你在fetch事件里收到的事件对象其request属性就是一个 Request 实例。你要做离线缓存得判断request.method、读取request.url、然后决定是从 Cache API 取还是转发给网络。如果你不理解 Request 对象Service Worker 基本就写不了。而 Response 对象同理——在 Service Worker 里你可以完全凭空new Response()造一个响应出来也可以从缓存里拿一个 Response 直接返回给页面。这也就是为什么 Fetch API 早就不只是一个浏览器发请求的工具而是整个 Web 网络层的基石。2. Request 对象全解析从构造到消费的完整链路2.1 构造一个 Request参数和 init 配置项创建 Request 对象用new Request(input, init)。input可以是 URL 字符串也可以是另一个 Request 对象此时会基于原请求克隆出一个新请求。init是一个配置对象最常用的配置项我整理成了表格配置项类型作用踩坑提示methodstringHTTP 方法默认 GET大小写敏感headersHeaders / 对象 / 数组请求头注意Content-Type不手动设置时浏览器会根据 body 类型自动设置body多种类型请求体GET/HEAD 请求不能带 bodymodestring请求模式cors、no-cors、same-origincredentialsstring凭证模式same-origin、include、omitcachestring缓存模式控制浏览器 HTTP 缓存redirectstring重定向模式follow、error、manualsignalAbortSignal取消请求配合 AbortController 使用referrerstring来源一般用不到integritystring子资源完整性校验非必要不设置这里我要重点强调一个在真实项目中反复出现的坑headers 是 Headers 对象不是普通对象。虽然 Fetch 规范允许你在init.headers里传普通对象但一旦 Request 创建完成你要读取或修改请求头必须用request.headers的方法比如request.headers.get(Content-Type)、request.headers.set(X-Token, xxx)。我见过太多人直接request.headers[X-Token] xxx结果发现怎么加都加不上去就是因为没有理解 Headers 是一个拥有自己方法的接口。2.2 只读属性背后的设计逻辑为什么你改不了请求Request 创建出来之后它的method、url、mode、credentials这些属性全是只读的。你试图request.method POST代码不会报错但没有一点效果严格模式下可能直接抛错。这个设计初看有点反直觉但仔细想想是合理的Request 代表的是一次已经定型的 HTTP 请求如果你能随意改它的方法、改它的 URL那整个请求的意义就变了中间的缓存、签名、预检逻辑全乱套。真正需要改请求的时候正确姿势是复制一份再改。规范提供了clone()方法。需要注意clone()不是简单拷贝它复制出来的新请求是独立的改新请求不会影响旧请求。但有个限制如果原请求的 body 已经被读取比如你调用了req.text()就不能再 clone 了否则会抛TypeError。我实际项目里的做法是定义一个函数createApiRequest(baseUrl, extraConfig)每次调用返回一个全新的 Request 对象用参数控制差异避免 clone 的 bodyUsed 限制。2.3 必须掌握的 Request 实例方法Request 上有两组方法一组是请求体的读取方法arrayBuffer()、blob()、formData()、json()、text()另一组是clone()。第一组其实是 Body 混入提供的我会在第四章展开细说这里只说clone()和整体使用逻辑。在实际开发中我一般不会直接new Request()再传给 fetch因为fetch()本身接受 Request 对象但如果你传入 Request它会自动 clone 一份再用。你要是碰上请求体被读了所以传进去直接报错的情况八成就是因为忘了这层克隆机制。最简单的用法是// 先构造 Request const req new Request(/api/user, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ id: 1 }) }); // 把 Request 直接交给 fetch const res await fetch(req); // 如果后面还要重新发一次同样的请求先 clone 再传 const req2 req.clone(); const res2 await fetch(req2);3. Response 对象全解析服务器回应的每个细节3.1 你拿到的 Response 长什么样fetch()返回的 Promise 在 HTTP 响应头到达时就会 resolve哪怕状态码是 500 或者 404。这一点非常重要很多人以为fetch只有在网络层面失败时才 reject其实不是——HTTP 状态码不会让 Promise 进入 reject 状态只有断网、跨域失败、请求被中断这类根本没拿到响应的情况才会 reject。Response 对象主要包含这些属性属性类型说明statusnumberHTTP 状态码如 200、404、500statusTextstring状态文本如 OK、Not Foundokboolean等价于status 200 status 300headersHeaders响应头bodyReadableStream响应体流bodyUsedboolean响应体是否已被读取typestringbasic、cors、opaque等urlstring最终响应的 URL重定向后可能是新 URLredirectedboolean是否经历过重定向其中最容易让新人迷糊的是type。type basic表示同源响应type cors表示跨域且服务端给了正确的 CORS 头type opaque出现在mode: no-cors时你拿到的 Response 几乎是个黑盒——状态码是 0body 是 null什么都读不了。我强烈建议除非你在做script、img这类 no-cors 兼容否则别用mode: no-cors。3.2 手动构造 ResponseService Worker 的魔法很多人不知道Response 是可以new出来的。这在 Service Worker 里极其常用你在 Service Worker 里拦截了请求发现本地缓存里有数据可以直接new Response(cachedData, { status: 200, headers: { Content-Type: application/json } })丢回去给页面根本不用真去服务器。离线的时候还可以用Response.error()生成一个错误的网络响应或者用Response.redirect(url, status)做重定向。我举个简单的例子假设你在 Service Worker 里做了一个离线优先的策略self.addEventListener(fetch, (event) { const url new URL(event.request.url); // 如果请求的是 API 里的用户信息先查缓存 if (url.pathname.startsWith(/api/user/)) { event.respondWith( caches.match(event.request).then((cached) { if (cached) { return cached; } // 没缓存网络请求同时写进缓存 return fetch(event.request).then((response) { const copy response.clone(); caches.open(api-cache).then((cache) cache.put(event.request, copy)); return response; }); }) ); } });关键在于response.clone()—— 因为你要把响应同时用于返回给页面和写入缓存而 Response 的 body 只能被消费一次不 clone 的话第二次读取就会报错。这是 Body 混入的核心限制我在第四章会专门展开。3.3 判断响应的正确姿势我见过很多初学代码是这样的const res await fetch(/api/data); if (res.ok) { const data await res.json(); // 处理 data }这段代码在大多数情况没问题但有一个隐蔽的坑res.ok只判断 200 到 299如果后端约定用 200 包装业务失败比如{ code: 10001, message: 余额不足 }res.ok是 true但业务上其实是失败的。所以成熟一点的做法是先用 HTTP 状态码判断网络层是否正常再读 body 里的业务码判断业务是否成功。我自己的通用处理函数长这样async function request(url, options {}) { const res await fetch(url, options); // 无论什么状态码先把文本读出来方便统一处理错误 const text await res.text(); let data null; try { data text ? JSON.parse(text) : null; } catch (e) { // 不是 JSON就当文本 data text; } if (!res.ok) { const error new Error(data?.message || HTTP ${res.status}); error.status res.status; throw error; } return data; }这里我特意先res.text()再自己JSON.parse而不是直接用res.json()好处有两个一是你可以拿到原始文本做日志排查后端返回的异常但非 JSON内容时非常有帮助二是避免res.json()在响应体为空时抛 SyntaxError。4. Body 混入Body mixin深度拆解一次请求体的完整旅程4.1 Body 混入是什么东西Body 混入这个翻译有点绕英文原词是Body mixin。在 Web 规范里mixin 是指一种被多个接口共用的一组属性和方法。具体到 Fetch APIRequest 和 Response 各自需要处理请求体/响应体但读取 body 的逻辑是完全一致的——都是要把一个ReadableStream转成文本、JSON、Blob、ArrayBuffer、FormData 这些格式。于是规范设计者就把这组能力提取成一个独立的接口叫 Body再分别混入 Request 和 Response。你可以把 Body 理解成一个公共充电协议Request 和 Response 是两个不同品牌的手机Body 就是那个通用的快充头谁插上都是用同一套方案把电量数据取出来。Body 混入提供了以下成员body一个ReadableStream包含 body 数据的字节流bodyUsed布尔值标识 body 是否已经被读取过arrayBuffer()读取为 ArrayBufferblob()读取为 BlobformData()读取为 FormDatajson()读取为 JSONtext()读取为文本4.2 body 与 bodyUsed一次性筷子逻辑前面反复提到body 只能消费一次这必须说透。无论是 Request 还是 Responsebody 都是一次性筷子。当你调用了res.text()body 流就开始被读取读完之后bodyUsed会变成true这时候再调用res.json()浏览器会直接抛TypeError: Body is unusable。这其实不是 bug而是刻意设计。为什么这么设计因为 body 是流式的。在浏览器底层响应体的数据是从网络一点一点到达的它是一个流不是一个已经全部缓存好的对象。一旦你开始读取这个流数据就只能从头到尾走一遍。如果你想要既看文本又看 JSON就得在读之前先clone()一份然后两个副本各读各的。这条规则对 Request 和 Response 一视同仁。在实际项目中最常见的报错场景出现在函数内部先读了一次外部又读了一次async function fetchJson(url) { const res await fetch(url); // 有些人习惯先 console.log 一下原始数据 console.log(await res.text()); // 这里把 body 读掉了 return res.json(); // 这里再读直接报错 }我的心得是永远让读取 body这件事发生在离使用最近的地方不要预先读一次看看。若真要调试就用res.clone()去读那个副本别碰原身。4.3 五大读取方法的选择与实战取舍每个读取方法背后对应的是不同的使用场景选择错误会直接影响代码可读性和性能text()通用性最强。你拿到的所有 body 本质上都是字节流text()负责把字节按 UTF-8 解码成字符串。适合纯文本、JSON 字符串、HTML 片段也适合先读出来再自己 parse的错误处理。json()在text()基础上再做一次 JSON.parse。它是缩写不是魔法。所以当响应体不是合法 JSON 时会抛出 SyntaxError。适合结构化的 API 数据。blob()适合二进制大文件比如图片、音频、视频。Blob 对象保留了type信息可以用在URL.createObjectURL()上做预览也可以用来下载。arrayBuffer()适合需要直接操作二进制的场景比如做加密、哈希、解析文件格式。它跟 Blob 的区别是ArrayBuffer 是内存里的原始字节不包含文件类型信息。formData()用于解析multipart/form-data类型的响应体。目前浏览器端用得不多但在 Node 18 的全局 fetch 里偶尔会用到。用一个表格方便大家记忆方法底层行为适用场景失败时机text()读流 - 解码 UTF-8文本类内容流读取中断json()text() JSON.parse标准 API 数据JSON 语法错误blob()读流 - 收集为 Blob图片、音视频流读取中断arrayBuffer()读流 - 收集字节加密、哈希、二进制解析流读取中断formData()读流 - 解析 multipart表单类响应Content-Type不符4.4 手动构造 BodyRequest 里都能塞什么Body 混入不只是读的能力也规定了写的能力——你要用 Request 发请求体或者用new Response(body)造响应体时body 参数可以是这些类型string最常见注意配合Content-Type头。如果传普通字符串但不手动设置Content-Type浏览器不会自动给你加application/json所以发 JSON 的时候要么用JSON.stringify 手动指定头要么直接传Blob再指定类型。FormData浏览器会自动设置Content-Type: multipart/form-data; boundary...。这里有个经典坑如果你手动设置了Content-Typeboundary 可能丢失后端解析失败。所以传 FormData 时最好让浏览器自动处理 Content-Type别手贱去覆盖。URLSearchParams等同于表单的application/x-www-form-urlencoded但注意浏览器不会自动设置该 Content-Type需要手动加Content-Type: application/x-www-form-urlencoded。Blob适合在请求体里传具体类型的二进制比如上传图片时new Blob([fileData], { type: image/jpeg })。ArrayBuffer/TypedArray/DataView适合需要精确控制字节的协议场景。ReadableStream最强大的方式可以边读边传适合大文件流式上传。这也是为什么理解 Body 混入和 Stream 紧密相关的原因。我之前团队里有个新同事上传文件时非要手动给 FormData 请求加Content-Type: application/json结果后端一直说boundary 缺失查了好久才发现是这个原因。这个教训写进文档之后组里再也没有人犯过了。5. 实操从零手写一个带你吃透 Body 混入的完整示例5.1 场景设定文件上传 JSON 响应 大文件下载理论终归要落地。我来设计一个能覆盖 Request、Response、Body 混入核心用法的综合场景前端构造一个 FormData里面包含用户 ID 和文件把 FormData 塞进 Request 对象向/api/upload发送 POST服务端校验之后返回 JSON内容是上传文件的信息前端读取 Response 的状态和业务码紧接着模拟一个下载接口/api/download/:id返回文件 Blob前端用blob()读取并触发下载。这样一趟下来Request 构造、Request body、Response 判断、Response json、Response blob 全部覆盖了。5.2 代码实现与逐步讲解// 1. 构造 FormData const form new FormData(); form.append(userId, 9527); form.append(file, fileInput.files[0]); // 2. 用 Request 对象封装上传请求 const uploadRequest new Request(/api/upload, { method: POST, body: form // 注意不要手动设置 Content-Type让它自动生成 boundary }); // 3. 发请求 let response; try { response await fetch(uploadRequest); } catch (err) { console.error(网络层失败, err); return; } // 4. 先判断 HTTP 状态 if (!response.ok) { console.error(HTTP 错误, response.status, response.statusText); return; } // 5. 读取 JSON 响应 const result await response.json(); if (result.code ! 0) { console.error(业务错误, result.message); return; } const fileId result.data.fileId; // 6. 模拟下载该文件 const downloadResponse await fetch(/api/download/${fileId}); if (!downloadResponse.ok) { console.error(下载失败); return; } // 7. 用 blob() 读取并用 URL.createObjectURL 触发下载 const fileBlob await downloadResponse.blob(); const url URL.createObjectURL(fileBlob); const a document.createElement(a); a.href url; a.download file-${fileId}.jpg; a.click(); URL.revokeObjectURL(url);这个示例里最值得注意的就是第 2 步我们创建了 Request 对象但没有手动设置Content-Type。FormData 的 boundary 是浏览器在new Request()时根据 body 类型自动生成的。如果你改成new Request(url, { method: POST, headers: { Content-Type: application/json }, body: form })大概率会出现后端解析 body 失败的情况。5.3 用 Body 混入做流式分段读取前面几种读取方法都是一次性把整个 body 读进内存。但如果文件很大比如日志、视频一次读取会占大量内存甚至拖垮页面。这时候就该用 Body 混入里的body流配合ReadableStream做分段处理了。const res await fetch(/api/large-log); if (!res.ok || !res.body) { console.error(无法获取流); return; } const reader res.body.getReader(); const decoder new TextDecoder(utf-8); let receivedLength 0; const chunks []; while (true) { const { done, value } await reader.read(); if (done) break; chunks.push(value); receivedLength value.length; console.log(已接收 ${receivedLength} 字节); } // 合并分段字节并解码为完整文本 const totalBytes new Uint8Array(receivedLength); let offset 0; for (const chunk of chunks) { totalBytes.set(chunk, offset); offset chunk.length; } const fullText decoder.decode(totalBytes); console.log(fullText);这就是 Body 混入的底层真相res.text()、res.json()等方法只是帮你把这个 while 循环封装好了的高级 API。当你需要控制内存或实现进度条时就亲自去操作res.body这个 ReadableStream。这也是很多人学了 Fetch API 很久却完全不知道的能力建议你亲手跑一遍上面的代码对流的理解会上一个台阶。6. 常见问题与排查技巧实录6.1 failed to fetch到底是谁的问题TypeError: Failed to fetch是前端社区出现频率最高的报错之一。这句话本身非常没有信息量因为它涵盖了从断网、跨域失败、请求被浏览器拦截、到服务器直接吞掉连接的所有情况。我在排查这个报错时有一套固定流程打开 DevTools 的 Network 面板看请求到底有没有发出去如果请求是红色的点击查看详情是 CORS 错误、证书错误、还是根本没连上如果是 CORS 错误重点看Access-Control-Allow-Origin响应头是否存在、是否匹配如果用到了自定义请求头检查服务端是否放开了对应的Access-Control-Allow-Headers如果请求发出去但一直 pending可能是服务器响应超时或者连接被重置。注意一个很容易误判的点HTTP 500 不会导致 failed to fetch。只要响应头到达浏览器fetch 的 Promise 就是 resolved 状态。所以如果你的前端代码里出现了 failed to fetch优先去查网络层和跨域层别急着甩锅给后端业务逻辑。6.2 request header is too large怎么办这个报错也是我经常遇到的。字面意思是请求头太大服务器或代理直接拒绝了。常见诱因有Cookie 太大、自定义请求头塞了太多数据比如有人为了图省事把整个待搜索的大 JSON 塞进了 header 而不是 body、或者经过网关时头被反复追加导致膨胀。排查思路很直接先用浏览器 DevTools 看请求头体积。一个非常重要的经验是——Cookie 往往是头体积爆炸的元凶。有些站点域名下积累了非常多的 Cookie每次请求都会自动带上一旦超过服务器如 Nginx 默认large_client_header_buffers通常为 4 个 8k的限制就会报这个错。解决方案清理无效和过期 Cookie降低自动携带的头部体积把大数据从 header 挪到 bodyheader 只放鉴权 token、traceId 这类短字段如果前端无法控制比如第三方 Cookie 太多需要协调服务端或网关放开 header 大小限制对于自定义 token 过大的情况一言以蔽之该换访问凭证方案就换别硬塞在头里。6.3 收到 429 Too Many Requests 的优雅退避API 被限流429是另一个常见现象。很多新人一看 429 就慌以为自己的请求写错了。其实 429 表示请求量超过服务端允许的阈值一旦触发正确的做法不是盲目重试而是读响应头里的Retry-After按服务端要求的时间等待后再试。配合指数退避策略可以写一个简单的重试函数async function fetchWithRetry(url, options {}, retries 3) { let attempt 0; while (attempt retries) { const res await fetch(url, options); if (res.status ! 429) { return res; } const retryAfter Number(res.headers.get(Retry-After)) || 2 ** attempt * 1000; attempt 1; await new Promise((resolve) setTimeout(resolve, retryAfter)); } throw new Error(请求重试次数已用完); }这里用了指数退避的简化版本把等待时间传给 setTimeout。实际项目中还要注意并发请求同时收到 429 时要加一个全局的节流闸避免所有请求在同一瞬间重试造成雪崩。6.4 bodyUsed 被误用导致崩溃我见过不少人在项目里写类似这样的代码const res await fetch(/api/user); if (res.status 200) { const user await res.json(); renderUser(user); } // 在另一个地方想再用一下响应 const text await res.text(); // 报错Body is unusable原因我在第四章讲过Body 只能被消费一次。这时候要么在一开始就const copy res.clone()把副本留作备用要么干脆在设计上避免对同一个 Response 做二次读取。我个人的习惯是每个 Response 对象只对应一个读取语义。需要 JSON 就一路 JSON需要文本就一路文本不要中间切换。6.5 CORS 预检失败的排查顺序当你的请求带有自定义头、非简单方法PUT/DELETE等或Content-Type: application/json时浏览器会先发一个OPTIONS预检请求。如果这个预检没有通过你会在控制台看到 CORS policy: No Access-Control-Allow-Origin header is present on the requested resource。排查顺序看预检请求的响应头确认是否返回了Access-Control-Allow-Origin且值是否匹配前端来源看是否有Access-Control-Allow-Headers且是否包含你发送的自定义头看是否有Access-Control-Allow-Methods且是否包含你要用的方法如果服务端在网关层做了鉴权确认 OPTIONS 请求不会被业务鉴权拦截。需要特别提醒的是开发环境下设置代理请求同源接口和线上跨域直连两者的 CORS 表现可能完全不同。不要拿开发环境的现象去推断线上环境最好直接在生产环境域名下验证一次。7. 一些来自实际项目的经验心得写到这里我想分享一个组内新人培训时常用的总结遇到 fetch 相关的问题先问自己三个问题——请求对象构造对了没有响应对象的状态判断了没有body 被读了几次90% 的报错都逃不出这三件事。在真实项目里我现在几乎不会直接用fetch那层 API而是会在上面再封一层请求客户端内部统一处理 token 注入、超时取消、错误格式化、429 退避。但这层封装不管怎么写底层利用的依然是 Request、Response 和 Body 混入的能力——弄清楚底层机制封装才不会写出碰运气的代码。如果你读完这篇还是觉得记不住我建议下一个项目里你尝试做两件事一是找一个完整的 Request 对象console.log出来把每个属性看一遍二是故意写一段先读 text 再读 json的代码亲眼看看那个 TypeError记住body 只能消费一次这句话。踩过一次坑之后你就真正理解 Body 混入为什么存在了。