返回探索
指南VibeFix 内容整理更新于 2026年11月20日

别再让请求悄悄失败:Fetch 实战指南

点单页要从后端拿菜单、提交订单,靠的都是 fetch()。本文按 MDN 的《使用 Fetch API》官方文档讲清楚:默认 GET、404 不拒收、五种读法、POST 发 JSON、请求头、跨域三档、凭证三档、取消请求、身体只能读一次与流式读法。

真实照片:机房里一排黑色服务器机柜,密密麻麻的灰蓝色网线缠绕在机柜之间

先把这篇的边界说清楚。站里已经有《CORS 跨域实战指南》,讲的是服务端怎么配头、预检怎么通过;还有《API 韧性:熔断实战指南》,讲的是请求失败了怎么重试、怎么熔断;还有《Promise 与 async/await 实战指南》,讲的是等一个结果回来有几种写法;还有《事件循环实战指南》,讲的是代码到底什么时候跑。这篇不讲服务端配头、不讲重试熔断、不讲 Promise 的写法,只讲一件事:浏览器里的 fetch() 这一句怎么写、发出去的是什么、回来的是什么。下面用到的“青石咖啡馆”还是那个虚构的练手项目:一个帮街边咖啡馆做点单的网页小工具。这回讲的是它的点单页:页面要从后端拿菜单、提交订单、取消一次发错的请求。本文所有以它为例的操作、代码和数字,都是为了讲清楚做法编出来的,不是真实记录。所有关于 Fetch 的语法和行为,都来自 MDN 的《Using the Fetch API(使用 Fetch API)》官方文档,来源见每篇的 meta 信息与 evidence 记录。文档里的例子,比如 example.org、products.json、用户名 example,都是文档自带的示例,不是真实服务。

第一步:fetch() 最小写法,默认就是 GET

发一个请求,最短只要一行:const response = await fetch("https://example.org/products.json")。MDN 的说法是:要发请求就调用 fetch(),传一个要取的资源的定义,可以是 URL 字符串、URL 对象,也可以是一个 Request 实例;不传第二个参数,默认就是 GET 请求。fetch() 返回一个 Promise,浏览器一收到响应的状态和头就兑现了,给你一个 Response 对象——注意,这时候响应体可能还没收完,状态和头先到、身体后到。咖啡馆的点单页就是这么拿菜单的:const response = await fetch("/api/menu"),一行发出,response 就是那次请求的回执。记住第一句话:fetch() 默认 GET,兑现时你拿到的是回执 Response,不是已经读好的数据。

第二步:404 不会让 fetch 拒收,先查 ok 再读数据

这是 Fetch 里最容易踩的坑,MDN 专门用一段讲清楚:fetch() 返回的 Promise 只在网络错、坏的 URL 方案这类问题上才拒收;服务器回了 404、500 这样的错误状态,Promise 照样兑现,给你一个 Response。也就是说,请求发出去、服务器也回话了,哪怕回的是“没有这个东西”,fetch 也认为是成功了。所以读数据之前必须先查状态:response.status 是数字状态码,response.ok 只在状态码落在 200 到 299 这一段时才是 true。MDN 给的惯用写法是:if (!response.ok) { throw new Error(`Response status: ${response.status}`); },先把错误状态拦下来、抛出去,再往下读。咖啡馆的点单页就踩过这个坑:菜单接口下线回了 404,前端没查 ok,直接对着 404 的页面内容调 response.json(),结果 JSON 解析报错,页面上显示的却是“解析失败”,真正的病因“接口没了”被盖住了。记住判断句:fetch 兑现不等于请求成功,先看 ok,再读身体。

第三步:读身体有五种方法,按内容类型选

Response 提供了五种读身体的方法,全是异步方法、返回 Promise:arrayBuffer()、blob()、formData()、json()、text()。读哪种,看内容是什么:JSON 数据用 json(),纯文本用 text(),图片用 blob() 再转成本地地址,表单数据用 formData(),二进制用 arrayBuffer()。MDN 有一个取图片的完整例子:const response = await fetch("flowers.jpg"),先查 ok,再 const blob = await response.blob(),然后 const objectURL = URL.createObjectURL(blob),最后 image.src = objectURL,图片就显示出来了。blob 适合图片、文件这类二进制内容,读完再用 URL.createObjectURL 挂到页面上,不用先把整张图变成文本。方法会抛错,比如对一段不是 JSON 的内容调 json(),解析失败就抛出来。所以稳妥的做法是先看响应头再读:const contentType = response.headers.get("content-type"); if (!contentType || !contentType.includes("application/json")) { throw new TypeError("Oops, we haven't got JSON!"); },这是 MDN 的 fetchJSON 例子原样。咖啡馆的订单提交就是这么写的:先确认 content-type 里有 application/json,再调 response.json(),后端偶尔回一段报错纯文本时,前端能报出“回来的不是 JSON”,而不是含糊的解析错。记住判断句:先看内容类型,再选读法;json() 只读真 JSON。

第四步:POST 发 JSON,三件套缺一不可

默认是 GET,想发 POST 就在第二个参数里写 method。MDN 的例子是:const response = await fetch("https://example.org/post", { method: "POST", body: JSON.stringify({ username: "example" }), headers: { "Content-Type": "application/json" } })。三件套缺一不可:method 告诉服务器这是什么动作,body 是发过去的载荷,Content-Type 告诉服务器载荷是什么格式。注意 body 必须已经是字符串:JSON.stringify 把对象变成字符串再传;如果把对象直接传给 body,MDN 说了,其他对象会被拿去调 toString(),结果就是 "[object Object]",服务器收到的是一串没用的字。咖啡馆提交订单就是这么写的:body: JSON.stringify({ dish: "拿铁", count: 2 }),头里写 Content-Type: application/json,后端按 JSON 解析,一次成功。记住判断句:POST 发 JSON,method、body、Content-Type 三件套齐了再发。

第五步:请求头两种写法,Headers 对象多一层清洗

请求头告诉服务器关于这次请求的信息,比如 POST 的 Content-Type 就是在说身体是什么格式。设请求头有两种写法:一是直接在 headers 选项里写一个对象字面量,二是先 new Headers(),用 append() 一条条加,再把这个 Headers 对象交给 headers 选项。MDN 说了,用 Headers 对象的好处是多一层输入清洗:它会把头名归一化成小写、去掉头值前后的空白,还会拦住某些不让设的头。很多头是浏览器自动设的、脚本改不了,这些叫禁用的请求头;如果 mode 设成 no-cors,能设的头还要再少一圈。咖啡馆的点单页用的是对象字面量写法:headers: { "Content-Type": "application/json" },简单够用;要动态拼多个头、或者想让浏览器多管一层的时候,再换 Headers 对象。记住判断句:头少用对象字面量,头多或者想多一层清洗用 Headers 对象;浏览器自动设的头,别想改。

第六步:GET 没有身体,参数拼进查询串

GET 请求不能带 body,但照样能给服务器传数据:把数据拼到 URL 后面当查询串。MDN 的做法是用 URLSearchParams 编码,再拼到 URL 上:const params = new URLSearchParams(); params.append("username", "example"); const response = await fetch(`https://example.org/login?${params}`),发出去的就是 https://example.org/login?username=example。URLSearchParams 会替你处理编码,用户名里有空格、中文、特殊符号也不用自己操心。反过来,URLSearchParams 也能当 POST 的 body,配上 application/x-www-form-urlencoded,服务器按表单解析。咖啡馆的菜单筛选就是这么写的:params.append("category", "热饮"),再拼到 /api/menu 后面,刷新列表不用改别的代码。记住判断句:GET 传参走查询串,用 URLSearchParams 拼,别手写问号和等号。

第七步:body 能传九种东西,文件直接当身体发

请求体是客户端发给服务器的载荷,MDN 列了能当 body 传的九种类型:字符串、ArrayBuffer、TypedArray、DataView、Blob、File、URLSearchParams、FormData、ReadableStream。文件上传就是直接把 File 当 body 发,表单就用 FormData,二进制就用 ArrayBuffer 或者 TypedArray。还是那条老规矩:这九种之外的对象会被拿去调 toString(),所以传对象之前先自己转成字符串或者 FormData。咖啡馆的“上传今日特价图”就是这么写的:body 直接传用户选的 File,头都不用多写,浏览器自己会处理。记住判断句:传 body 之前先问一句:它在 MDN 那九种里吗?不在就先转。

第八步:mode 三档管跨域,opaque 响应什么都看不见

能不能跨域发请求,看 RequestInit.mode 这一项,有 cors、same-origin、no-cors 三档。fetch 的默认值是 cors:跨域时走 CORS 机制。如果是简单请求,请求一定会发出去,但服务器必须回正确的 Access-Control-Allow-Origin 头,浏览器才把响应交给调用方;如果不是简单请求,浏览器先发一个预检请求,确认服务器懂 CORS、也允许,这才发真正的请求。same-origin 是彻底不让跨域。no-cors 是关掉跨域的 CORS:方法只剩 GET、HEAD、POST,能设的头也受限,拿到的响应是 opaque,也就是说头和身体都看不见。MDN 的原话是:大多数网站不该用 no-cors,它主要用在某些 service worker 的场景。opaque 响应的特征要背下来:status 是 0,头列表是空的,body 是 null。本篇只讲 fetch 这一侧的三档开关,服务器那头该回什么头、预检怎么配,是《CORS 跨域实战指南》的事。记住判断句:日常只用默认的 cors;拿到 status 0 的响应,先问是不是走了 no-cors。

第九步:credentials 三档管凭证,跨域带凭证要服务器点头

Fetch 语境里的凭证,是跟着请求走、服务器用来认人的额外数据:HTTP cookie、TLS 客户端证书、Authorization 头和 Proxy-Authorization 头。credentials 选项有三档:omit 从来不带凭证;same-origin 是默认值,只给同源请求带;include 不管同源跨域都带。但有两道关:第一,cookie 的 SameSite 属性如果是 Strict 或者 Lax,跨站时就算 credentials 设了 include,cookie 也不会发;第二,跨域带凭证会让网站容易受 CSRF 攻击,所以服务器还得点头才行:回 Access-Control-Allow-Credentials 头,而且 Access-Control-Allow-Origin 必须写明具体的来源,不能写星号。少了任何一个,浏览器会报网络错。MDN 还分了两种情况:简单请求是带着凭证发出去、服务器不点头就报网络错;非简单请求是先发一个不带凭证的预检,服务器点头了才发带凭证的真请求。咖啡馆的点单页登录后调订单接口,用的就是 credentials: "include",配合同源的订单服务,一次写对。记住判断句:跨域带凭证,客户端和服务器两边都要点头,少一边就报网络错。

第十步:Request 对象能复用,还能派生改一点

Request 构造器接受的参数和 fetch() 本身一模一样:想传给 fetch 的选项,也能先传给 new Request(),再把造好的对象传给 fetch()。MDN 的例子是:const myRequest = new Request("https://example.org/post", { method: "POST", body: JSON.stringify({ username: "example" }), headers: myHeaders }),然后 const response = await fetch(myRequest)。好处是能复用:同一个请求定义到处传;还能派生:new Request(request1, { body: JSON.stringify({ username: "example2" }) }),从 request1 复制一份、只改 body。MDN 的 post(request) 例子就是这么用的:一个函数接 Request、调 fetch、读 json、打印成功,两个派生出来的请求先后传进去,各自跑各自的。咖啡馆的点单页把“提交订单”包成了一个 Request 模板:基础头和地址写一次,不同订单只换 body。记住判断句:同一个请求要发两次以上,先造 Request;只改一处,从旧的派生新的。

第十一步:取消请求用 AbortController,晚了也会报错

想让一次请求能取消,就造一个 AbortController,把它的 signal 交给请求的 signal 属性;要取消就调控制器的 abort() 方法,fetch() 的 Promise 会以 AbortError 这个异常拒收。一个控制器也能管多个请求:把同一个 signal 交给几个 fetch,abort 一按,几个一起停,适合“换分类时停掉全部旧请求”这种场景。MDN 的例子是两个按钮:一个按钮点“开始取数”,另一个点“取消”,取消按钮一按,controller.abort(),正在跑的 fetch 立刻以 AbortError 拒收,catch 里打印 Error。还有一个容易忽略的时点:请求已经兑现、响应体还没读完的时候再 abort,读身体也会以 AbortError 拒收。MDN 的 get() 例子就是这么写的:const response = await fetch(request) 之后调 controller.abort(),再调 await response.text(),这一行直接抛 AbortError。咖啡馆的点单页在用户切换菜单分类时用上了这一招:新分类一点,旧分类的请求立刻 abort,旧数据再也不会晚到一步、把新列表盖掉。记住判断句:能取消的请求才配 signal;取消要趁早,晚了读身体也会报错。

第十二步:身体是流,只能读一次,想读两次先克隆

请求和响应的身体其实都是 ReadableStream,读身体就是在流式地取内容。好处是省内存:浏览器不用先把整个响应缓存在内存里再交给你,你可以一块一块处理。代价是只能读一次:流一旦被挂上 reader 就是锁定的,内容一旦被读过就是已扰动的,别的就再也读不了。MDN 的例子是:const result1 = await response.json() 之后再调 const result2 = await response.json(),第二行直接抛错。想读两次,必须在读之前调 clone():const response2 = response1.clone(),两个各读各的,互不干扰。这个写法最常见的用途是 service worker 里做离线缓存:MDN 的 cacheFirst 例子是先查缓存,没有就 fetch,响应 ok 就 cache.put(request, networkResponse.clone()) 把克隆体存进缓存,再把原响应还给应用。请求体也一样:带身体的 Request 发两次会抛 "Body has already been consumed.",要先 clone() 再发。本篇只讲 fetch 这一侧的流规则,离线缓存怎么做见站里的离线指南。记住判断句:身体只能读一次,读之前想好要不要克隆。

第十三步:大文件别等整份,用流一块一块读

调 response.text() 要等整个文件收完才能开始处理,大文件会卡住。流式读法是直接拿 response.body,pipeThrough 一个 TextDecoderStream,再 for await 一块一块处理:const stream = response.body.pipeThrough(new TextDecoderStream()); for await (const value of stream) { console.log(value); }。MDN 提醒:直接读身体拿到的是原始字节,得自己转,这里的 TextDecoderStream 就是把 UTF-8 编码的身体解成文本。文档还给了一个更进一步的例子:用生成器按行读文本文件,正则找换行,一行一行产出,处理函数逐行消费。咖啡馆的点单页在拉“今日全部订单”这种大文本时用的是流式读法:订单一行到、页面一行显示,不用等整份到齐。记住判断句:小数据用 json()、text() 一次读完;大文件用流,一块一块处理。

第十四步:响应也有类型,先看 type 再读头

Response 还有一个 type 属性,告诉你这次响应是怎么来的,分四种:basic 是同源请求,cors 是走了 CORS 的跨域请求,opaque 是用了 no-cors 的跨域简单请求,opaqueredirect 是把 redirect 选项设成 manual、服务器又回了重定向状态。类型决定了你能看到什么:basic 的响应不含禁用响应头列表里的头,cors 的响应只含 CORS 安全列表里的头,opaque 和 opaqueredirect 的 status 是 0、头列表是空的、body 是 null。也就是说,跨域拿回来的响应,头不一定全给你看;先看 response.type,再决定读哪些头,别对着一个 opaque 响应找 Content-Type。咖啡馆的点单页在接第三方菜谱接口时就看过这个属性:响应 type 是 cors,头里只有安全列表里的那几个,自定义的 X-Menu-Version 读不到——不是后端没给,是 CORS 规则下浏览器不交给你。记住判断句:读头之前先看 type,opaque 响应里什么都没有。

第十五步:100 次请求事故,先对着图自查

虚构青石咖啡馆项目一个月 100 次 Fetch 请求事故的原因分布条形图

上图是虚构的青石咖啡馆项目一个月的统计:和 Fetch 请求相关的事故一共 100 次。忘查 ok、把 404 当成功 32 次,占 32.0%,是最多的;身体读了两次、第二次抛错 20 次,占 20.0%;没先查 content-type、对着非 JSON 调 json() 16 次,占 16.0%;POST 忘写 Content-Type、后端不认身体 14 次,占 14.0%;GET 请求带了 body 10 次,占 10.0%;跨域凭证没配齐、浏览器报网络错 8 次,占 8.0%。32 加 20 加 16 加 14 加 10 加 8 等于 100,账是平的。图里每一类都对应正文里的一步:忘查 ok 是第二步,身体读两次是第十二步,json() 错格式是第三步,POST 忘 Content-Type 是第四步,GET 带 body 是第六步,跨域凭证是第九步。这些数字是编出来的例子,目的是让你一眼看到:第一类占了快三分之一,而它的根源只有一个——fetch 兑现不等于请求成功,ok 必须先查。

自查清单:写完带 fetch 的代码,逐条打勾

第一,fetch() 默认 GET,兑现时拿到的是回执 Response,不是已经读好的数据。第二,404、500 不会让 fetch 拒收,先看 response.ok 再读身体,不 ok 就抛错。第三,读身体按内容类型选方法:json()、text()、blob()、arrayBuffer()、formData(),先看 content-type 再读。第四,POST 发 JSON 要齐三件套:method、JSON.stringify 后的 body、Content-Type: application/json。第五,头少用对象字面量,头多用 Headers 对象;浏览器自动设的头改不了。第六,GET 没有身体,参数用 URLSearchParams 拼进查询串。第七,body 只传 MDN 列的那九种类型,文件直接当身体发,对象先自己转。第八,日常只用默认的 cors;拿到 status 0 的响应,先问是不是走了 no-cors。第九,跨域带凭证要两边点头:客户端 credentials: "include",服务器回 Access-Control-Allow-Credentials,来源不能写星号。第十,同一个请求发两次以上,先造 Request;只改一处,从旧的派生新的。第十一,能取消的请求配 signal,取消按钮调 abort(),晚了读身体也会报 AbortError。第十二,身体是流,只能读一次,想读两次先 clone()。第十三,小数据一次读完,大文件用流一块一块读。第十四,响应分 basic、cors、opaque、opaqueredirect 四种类型,opaque 的 status 是 0、头是空的、身体是 null;读响应头之前先看 type。十四条里任何一条答不上来,回到对应的章节再读一遍,比多背十个 API 都有用。

阅读 3评论 0

评论 (0)

ME
0/1000
评论加载中...

原始来源

浏览项目广场发布你的项目

相关文章

真实照片:一排浅灰色金属档案柜,其中一个抽屉拉开,露出里面一排排悬挂的文件夹
指南
浏览器里也能用数据库:IndexedDB 本地存取实战指南

localStorage 只能存字符串、没有索引。IndexedDB 是浏览器里真正的数据库:能存结构化数据、容量大得多、能建索引、能用事务。本文按 MDN 的《Using IndexedDB》《IDBDatabase》《IDBObjectStore》三篇官方文档讲清楚:五步套路、开库、升级、主键、索引、事务、add 与 put、get、游标、范围与多标签页升级。

工具技巧数据工作流前端工程
真实照片:一双手在 MacBook Pro 上打字,屏幕显示改写 HTML 内容的 JavaScript 代码,白色桌面上有白色鼠标、纸张和文件夹
指南
别让函数把你绕晕:JavaScript 函数、参数与箭头函数实战指南

函数你每天都在调,这篇把你一直在做的事讲清楚。本文按 MDN 的《Functions》《Arrow function expressions》《Rest parameters》三篇官方文档讲清楚:声明与表达式、参数与实参、默认值、剩余参数、展开语法、返回值、箭头函数省写规则、this 的坑、回调与高阶函数、作用域。

工具技巧前端工程AI 编程实践
真实照片:木桌上的笔记本电脑、平板与手机同时显示同一个绿叶主题网站,手机上导航已折成单列,桌角有一盆绿植
指南
手机上缩成一团?响应式布局与媒体查询实战指南

同一个页面要在手机、平板、电脑上都站得住。本文按 MDN 的《Responsive web design》《Using media queries》《viewport meta 参考》三篇官方文档讲清楚:流式 HTML、viewport 标签、流式网格与 max-width、图片不撑破容器、媒体查询语法、按内容定断点、mobile-first、响应式字号、按能力查设备与上线检查清单。

移动应用设计体验前端工程