作者:阮一峰。原文发表于 2020 年 12 月 28 日:Fetch API 教程。本文保留完整技术章节和原文参考链接,并在 2026 年 10 月 5 日核查整理。原文采用 CC BY-NC-ND 3.0,作者归属不变。
阅读说明:下列请求地址、文件名、DOM 元素和变量是各自独立示例的上下文,不是一段可直接拼接运行的程序。原文示例通常省略状态检查、错误处理和 DOM 判空;有关风险已在相邻段落及文末标明。修订内容标作“编者校订”,未把静态审核称为执行测试。
fetch()是 XMLHttpRequest 的升级版,用于在 JavaScript 脚本里面发出 HTTP 请求。
浏览器原生提供这个对象。本文详细介绍它的用法。

一、基本用法
fetch()的功能与 XMLHttpRequest 基本相同,但有三个主要的差异。
(1)fetch()使用 Promise,不使用回调函数,因此大大简化了写法,写起来更简洁。
(2)fetch()采用模块化设计,API 分散在多个对象上(Response 对象、Request 对象、Headers 对象),更合理一些;相比之下,XMLHttpRequest 的 API 设计并不是很好,输入、输出、状态都在同一个接口管理,容易写出非常混乱的代码。
(3)fetch()可以通过响应体的 ReadableStream 分块处理数据。与通常一次性获取响应体的 XHR 用法相比,这种方式适合逐块处理下载内容;但调用 json()、text() 等便捷方法仍会等待并读取完整响应。编者校订:XHR 也有进度事件和部分渐进读取能力,不能把它概括成任何情况下都只能等到最后才看到数据。
在用法上,fetch()接受一个 URL 字符串作为参数,默认向该网址发出 GET 请求,返回一个 Promise 对象。它的基本用法如下。
fetch(url) .then(...) .catch(...)
下面是一个例子,从服务器获取 JSON 数据。
fetch('https://api.github.com/users/ruanyf') .then(response => response.json()) .then(json => console.log(json)) .catch(err => console.log('Request Failed', err));
上例拿到的是 Response 对象,不是 Stream 对象。流位于它的 body 属性中。response.json() 异步读完响应体并将内容解析为 JavaScript 值。编者校订:这里修正原文把 Response 本身称为流的表述。
Promise 可以使用 await 语法改写,使得语义更清晰。
async function getJSON() { let url = 'https://api.github.com/users/ruanyf'; try { let response = await fetch(url); return await response.json(); } catch (error) { console.log('Request Failed', error); } }
上例在 try...catch 中等待请求和 JSON 解析,以便在本函数内处理它们的失败。编者校订:await 并非语法上必须位于 try...catch;也可以让异常向调用方传播,由调用方统一处理。
后文都采用await的写法,不使用.then()的写法。
二、Response 对象:处理 HTTP 回应
2.1 Response 对象的同步属性
fetch()请求成功以后,得到的是一个 Response 对象。它对应服务器的 HTTP 回应。
const response = await fetch(url);
前面说过,Response 包含的数据通过 Stream 接口异步读取,但是它还包含一些同步属性,对应 HTTP 回应的标头信息(Headers),可以立即读取。
async function fetchText() { let response = await fetch('/readme.txt'); console.log(response.status); console.log(response.statusText); }
上面示例中,response.status和response.statusText就是 Response 的同步属性,可以立即读取。
标头信息属性有下面这些。
Response.ok
Response.ok属性返回一个布尔值,表示请求是否成功,true对应 HTTP 请求的状态码 200 到 299,false对应其他的状态码。
Response.status
Response.status属性返回一个数字,表示 HTTP 回应的状态码(例如200,表示成功请求)。
Response.statusText
Response.statusText属性返回一个字符串,表示 HTTP 回应的状态信息(例如请求成功以后,服务器返回”OK”)。
Response.url
Response.url属性返回请求的 URL。如果 URL 存在跳转,该属性返回的是最终 URL。
Response.type
Response.type属性返回请求的类型。可能的值如下:
basic:普通请求,即同源请求。cors:跨域请求。error:网络错误,主要用于 Service Worker。opaque:如果fetch()请求的mode属性设为no-cors,就会返回这个值,详见请求部分。表示发出的是简单的跨域请求,类似<form>表单的那种跨域请求。opaqueredirect:如果fetch()请求的redirect属性设为manual,就会返回这个值,详见请求部分。
Response.redirected
Response.redirected属性返回一个布尔值,表示请求是否发生过跳转。
2.2 判断请求是否成功
fetch() 返回的 Promise 是否兑现,与服务器返回的 HTTP 状态码是否代表业务成功,是两件事。网络失败、请求被取消或请求参数等错误可能让 Promise 拒绝;HTTP 404、500 等响应通常仍会兑现为 Response。因此拿到响应后还要明确检查状态,解析响应体也可能单独失败。
这就是说,即使服务器返回的状态码是 4xx 或 5xx,fetch()也不会报错(即 Promise 不会变为 rejected状态)。
只有通过Response.status属性,得到 HTTP 回应的真实状态码,才能判断请求是否成功。请看下面的例子。
async function fetchText() { let response = await fetch('/readme.txt'); if (response.status >= 200 && response.status < 300) { return await response.text(); } else { throw new Error(response.statusText); } }
上例把 2xx 状态视为成功。编者校订:默认 redirect: "follow" 会跟随重定向,但不会把任意 3xx 自动“转成 200”;最终地址仍可能返回 404、500 或其他结果。应检查最终 Response 的 ok 或 status。
另一种方法是判断response.ok是否为true。
if (response.ok) { // 请求成功 } else { // 请求失败 }
2.3 Response.headers 属性
response.headers 指向 Headers 对象,用于读取浏览器允许脚本看到的响应头。跨域响应只暴露 CORS 允许的头;Set-Cookie 等头不能作为普通前端 JavaScript 的可读响应头。
Headers 对象可以使用for...of循环进行遍历。
const response = await fetch(url); for (let [key, value] of response.headers) { console.log(`${key} : ${value}`); } // 或者 for (let [key, value] of response.headers.entries()) { console.log(`${key} : ${value}`); }
Headers 对象提供了以下方法,用来操作标头。
Headers.get():根据指定的键名,返回键值。Headers.has(): 返回一个布尔值,表示是否包含某个标头。Headers.set():将指定的键名设置为新的键值,如果该键名不存在则会添加。Headers.append():添加标头。Headers.delete():删除标头。Headers.keys():返回一个遍历器,可以依次遍历所有键名。Headers.values():返回一个遍历器,可以依次遍历所有键值。Headers.entries():返回一个遍历器,可以依次遍历所有键值对([key, value])。Headers.forEach():依次遍历标头,每个标头都会执行一次参数函数。
上面的修改方法属于通用 Headers 接口。编者校订:从网络响应得到的 Headers 通常不可修改,尝试写入可能抛出异常;请求头还受禁止设置的头名与 CORS 限制,不能把这些方法理解成浏览器允许任意改写网络头。
这些方法中,最常用的是response.headers.get(),用于读取某个标头的值。
let response = await fetch(url); response.headers.get('Content-Type') // application/json; charset=utf-8
Headers.keys()和Headers.values()方法用来分别遍历标头的键名和键值。
// 键名 for(let key of myHeaders.keys()) { console.log(key); } // 键值 for(let value of myHeaders.values()) { console.log(value); }
Headers.forEach()方法也可以遍历所有的键值和键名。
let response = await fetch(url); response.headers.forEach( (value, key) => console.log(key, ':', value) );
2.4 读取内容的方法
Response对象根据服务器返回的不同类型的数据,提供了不同的读取方法。
response.text():得到文本字符串。response.json():得到 JSON 对象。response.blob():得到二进制 Blob 对象。response.formData():得到 FormData 表单对象。response.arrayBuffer():得到二进制 ArrayBuffer 对象。
上面5个读取方法都是异步的,返回的都是 Promise 对象。必须等到异步操作结束,才能得到服务器返回的完整数据。
response.text()
response.text()可以用于获取文本数据,比如 HTML 文件。
const response = await fetch('/users.html'); const body = await response.text(); document.body.innerHTML = body
安全校订:上段保留原文示例供辨认风险:把不可信响应直接赋给 innerHTML 会引入 HTML 注入/XSS 风险。若目的只是展示文本,可使用下列修订版;若必须渲染 HTML,需要另行采用可信模板和经过审查的 HTML 清理策略,不能仅靠“来自同域”判断可信。
const response = await fetch('/users.html');
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const body = await response.text();
document.querySelector('#output').textContent = body;
差异:增加状态检查,将危险的 innerHTML 改为 textContent。页面应先存在 #output 元素;这段显示原始文本,不保留 HTML 排版。
response.json()
response.json()主要用于获取服务器返回的 JSON 数据,前面已经举过例子了。
response.formData()
response.formData()主要用在 Service Worker 里面,拦截用户提交的表单,修改某些数据以后,再提交给服务器。
response.blob()
response.blob()用于获取二进制文件。
const response = await fetch('flower.jpg'); const myBlob = await response.blob(); const objectURL = URL.createObjectURL(myBlob); const myImage = document.querySelector('img'); myImage.src = objectURL;
上面示例读取图片文件flower.jpg,显示在网页上。
response.arrayBuffer()
response.arrayBuffer() 将完整响应体读入一个 ArrayBuffer,适用于需要直接处理二进制字节的场景。下例读取音频文件,再交给 Web Audio 解码;它本身不是边下载边播放的流式解码。
const audioCtx = new window.AudioContext(); const source = audioCtx.createBufferSource(); const response = await fetch('song.ogg'); const buffer = await response.arrayBuffer(); const decodeData = await audioCtx.decodeAudioData(buffer); source.buffer = decodeData; // 编者更正:使用解码后的 AudioBuffer source.connect(audioCtx.destination); source.loop = true;
编者校订:原文将下载得到的 ArrayBuffer 直接赋给 source.buffer,混淆了编码字节与解码后的 AudioBuffer。本文把该行改为 source.buffer = decodeData;其类型依据见 AudioBufferSourceNode.buffer 文档。上例描述下载、解码和连接节点的流程,未经运行验证。另须注意:源代码没有调用 source.start(),因此不能单凭此段断言“已经播放”。实际播放还需在允许的用户手势流程中恢复 AudioContext 并启动节点。这里只保留原文演示解码过程,未进行音频播放测试。
2.5 Response.clone()
Stream 对象只能读取一次,读取完就没了。这意味着,前一节的五个读取方法,只能使用一个,否则会报错。
let text = await response.text(); let json = await response.json(); // 报错
上面示例先使用了response.text(),就把 Stream 读完了。后面再调用response.json(),就没有内容可读了,所以报错。
Response 对象提供Response.clone()方法,创建Response对象的副本,实现多次读取。
const response1 = await fetch('flowers.jpg'); const response2 = response1.clone(); const myBlob1 = await response1.blob(); const myBlob2 = await response2.blob(); image1.src = URL.createObjectURL(myBlob1); image2.src = URL.createObjectURL(myBlob2);
上面示例中,response.clone()复制了一份 Response 对象,然后将同一张图片读取了两次。
Response 对象还有一个Response.redirect()方法,用于将 Response 结果重定向到指定的 URL。该方法一般只用在 Service Worker 里面,这里就不介绍了。
2.6 Response.body 属性
Response.body属性是 Response 对象暴露出的底层接口,返回一个 ReadableStream 对象,供用户操作。
它可以用来分块读取内容,应用之一就是显示下载的进度。
const response = await fetch('flower.jpg'); const reader = response.body.getReader(); while(true) { const {done, value} = await reader.read(); if (done) { break; } console.log(`Received ${value.length} bytes`) }
response.body.getReader() 返回读取器 ReadableStreamDefaultReader,其异步 read() 方法给出 { done, value },而不是普通同步迭代器。使用前还应检查 response.ok,并考虑 body 为空的情况。
done 表示流是否结束;Fetch 字节流中的 value 通常是 Uint8Array,value.length 是这一块的字节数。要显示累计进度,需要自己累加;若响应没有可靠的总长度,就只能显示已接收字节,而不能保证得到准确百分比。这里修正原文“arrayBuffer 数组”的说法。
三、fetch()的第二个参数:定制 HTTP 请求
fetch()的第一个参数是 URL,还可以接受第二个参数,作为配置对象,定制发出的 HTTP 请求。
fetch(url, optionObj)
上面命令的optionObj就是第二个参数。
HTTP 请求的方法、标头、数据体都在这个对象里面设置。下面是一些示例。
(1)POST 请求
const response = await fetch(url, { method: 'POST', headers: { "Content-type": "application/x-www-form-urlencoded; charset=UTF-8", }, body: 'foo=bar&lorem=ipsum', }); const json = await response.json();
上面示例中,配置对象用到了三个属性。
method:HTTP 请求的方法,POST、DELETE、PUT都在这个属性设置。headers:一个对象,用来定制 HTTP 请求的标头。body:POST 请求的数据体。
注意,有些标头不能通过headers属性设置,比如Content-Length、Cookie、Host等等。它们是由浏览器自动生成,无法修改。
(2)提交 JSON 数据
const user = { name: 'John', surname: 'Smith' }; const response = await fetch('/article/fetch/post/user', { method: 'POST', headers: { 'Content-Type': 'application/json;charset=utf-8' }, body: JSON.stringify(user) });
JSON 字符串应与 Content-Type: application/json;charset=utf-8 配合。编者校订:Content-Type 不是每次 fetch 都无条件默认为纯文本;浏览器会根据 body 类型推断,字符串常对应 text/plain;charset=UTF-8,FormData、URLSearchParams 和 Blob 的行为不同,没有 body 的请求也不需要这个头。
(3)提交表单
const form = document.querySelector('form'); const response = await fetch('/users', { method: 'POST', body: new FormData(form) })
(4)文件上传
如果表单里面有文件选择器,可以用前一个例子的写法,上传的文件包含在整个表单里面,一起提交。
另一种方法是用脚本添加文件,构造出一个表单,进行上传,请看下面的例子。
const input = document.querySelector('input[type="file"]'); const data = new FormData(); data.append('file', input.files[0]); data.append('user', 'foo'); fetch('/avatars', { method: 'POST', body: data });
上传二进制文件时,不用修改标头的Content-Type,浏览器会自动设置。
(5)直接上传二进制数据
fetch()也可以直接上传二进制数据,将 Blob 或 arrayBuffer 数据放在body属性里面。
let blob = await new Promise(resolve => canvasElem.toBlob(resolve, 'image/png') ); let response = await fetch('/article/fetch/post/image', { method: 'POST', body: blob });
四、原文所覆盖的 fetch 配置项
下面保留 2020 年原文列出的配置项示例,它不是对今天所有 RequestInit 字段的穷尽清单,也不是要求每个请求都照抄的默认配置。尤其 referrerPolicy 的历史默认值已发生变化。当前字段定义见 RequestInit。
const response = fetch(url, { method: "GET", headers: { "Content-Type": "text/plain;charset=UTF-8" }, body: undefined, referrer: "about:client", referrerPolicy: "no-referrer-when-downgrade", mode: "cors", credentials: "same-origin", cache: "default", redirect: "follow", integrity: "", keepalive: false, signal: undefined });
fetch()请求的底层用的是 Request() 对象的接口,参数完全一样,因此上面的 API 也是Request()的 API。
这些属性里面,headers、body、method前面已经给过示例了,下面是其他属性的介绍。
cache
cache属性指定如何处理缓存。可能的取值如下:
default:默认值,先在缓存里面寻找匹配的请求。no-store:直接请求远程服务器,并且不更新缓存。reload:直接请求远程服务器,并且更新缓存。no-cache:将服务器资源跟本地缓存进行比较,有新的版本才使用服务器资源,否则使用缓存。force-cache:缓存优先,只有不存在缓存的情况下,才请求远程服务器。only-if-cached:只查缓存,未命中时返回 504;这种模式要求请求采用mode: "same-origin"。
mode
mode属性指定请求的模式。可能的取值如下:
cors:默认值,允许跨域请求。same-origin:只允许同源请求。no-cors:请求方法只限于 GET、POST 和 HEAD,并且只能使用有限的几个简单标头,不能添加跨域的复杂标头,相当于提交表单所能发出的请求。
credentials
credentials属性指定是否发送 Cookie。可能的取值如下:
same-origin:默认值,同源请求时发送 Cookie,跨域请求时不发送。include:允许跨域请求携带凭据,但 Cookie 仍受到 SameSite、域、路径、Secure 以及浏览器隐私策略限制。omit:一律不发送。
跨域发送凭据时可设置 credentials: "include"。下例是原文的 API 形式示意,实际服务应使用 HTTPS,并明确评估 CSRF。服务器还需返回允许凭据的 CORS 头及明确的调用方 origin,不能同时使用 Access-Control-Allow-Origin: *。仅设置 include 不能保证 Cookie 一定发送,也不能赋予读取任意跨域响应的权限。
fetch('http://another.com', { credentials: "include" });
signal
signal属性指定一个 AbortSignal 实例,用于取消fetch()请求,详见下一节。
keepalive
keepalive属性用于页面卸载时,告诉浏览器在后台保持连接,继续发送数据。
一个典型的场景就是,用户离开网页时,脚本向服务器提交一些用户行为的统计信息。这时,如果不用keepalive属性,数据可能无法发送,因为浏览器已经把页面卸载了。
window.onunload = function() { fetch('/analytics', { method: 'POST', body: "statistics", keepalive: true }); };
redirect
redirect属性指定 HTTP 跳转的处理方法。可能的取值如下:
follow:默认值,fetch()跟随 HTTP 跳转。error:如果发生跳转,fetch()就报错。manual:不自动跟随跳转。浏览器通常返回字段被过滤的opaqueredirect响应,不能依赖它读取目标 Location,或假定 url 已是新地址、redirected 已为 true。此处修正原文对浏览器行为的描述。
integrity
integrity属性指定一个哈希值,用于检查 HTTP 回应传回的数据是否等于这个预先设定的哈希值。
比如,下载文件时,检查文件的 SHA-256 哈希值是否相符,确保没有被篡改。
fetch('http://site.com/file', { integrity: 'sha256-abcdef' });
referrer
referrer属性用于设定fetch()请求的referer标头。
编者校订:referrer 不能任意伪造跨域来源;支持同源的相对或绝对 URL、空字符串以及 about:client。空字符串表示不发送 Referer。
fetch('/page', { referrer: '' });
referrerPolicy
referrerPolicy属性用于设定Referer标头的规则。可能的取值如下:
no-referrer-when-downgrade:原文记载的历史默认值,总是发送Referer标头,除非从 HTTPS 页面请求 HTTP 资源时不发送。no-referrer:不发送Referer标头。origin:Referer标头只包含域名,不包含完整的路径。origin-when-cross-origin:同源请求Referer标头包含完整的路径,跨域请求只包含域名。same-origin:跨域请求不发送Referer,同源请求发送。strict-origin:Referer标头只包含域名,HTTPS 页面请求 HTTP 资源时不发送Referer标头。strict-origin-when-cross-origin:现代浏览器通常使用的默认策略(还可受上下文策略影响)。同源请求时Referer标头包含完整路径,跨域请求时只包含域名,HTTPS 页面请求 HTTP 资源时不发送该标头。unsafe-url:不管什么情况,总是发送Referer标头。
五、取消fetch()请求
fetch()请求发送以后,如果中途想要取消,需要使用AbortController对象。
let controller = new AbortController(); let signal = controller.signal; fetch(url, { signal: controller.signal }); signal.addEventListener('abort', () => console.log('abort!') ); controller.abort(); // 取消 console.log(signal.aborted); // true
上面示例中,首先新建 AbortController 实例,然后发送fetch()请求,配置对象的signal属性必须指定接收 AbortController 实例发送的信号controller.signal。
controller.abort()方法用于发出取消信号。这时会触发abort事件,这个事件可以监听,也可以通过controller.signal.aborted属性判断取消信号是否已经发出。
下面是一个1秒后自动取消请求的例子。
let controller = new AbortController(); setTimeout(() => controller.abort(), 1000); try { let response = await fetch('/long-operation', { signal: controller.signal }); } catch(err) { if (err.name == 'AbortError') { console.log('Aborted!'); } else { throw err; } }
六、参考链接
- Network requests: Fetch
- node-fetch
- Introduction to fetch()
- Using Fetch
- Javascript Fetch API: The XMLHttpRequest evolution
编者补充:正确使用这些示例
响应体只能消费一次。应在读取前调用 clone();已使用或已锁定的响应体不能任意克隆。克隆不表示第二次 HTTP 请求,但两个分支消费速度差距过大时可能增加缓冲和内存使用。Blob 示例创建的对象 URL 在不再使用时应通过 URL.revokeObjectURL() 释放,不能在图片尚未读取完时提前撤销。
上传数据要让类型与内容一致。FormData 的 multipart 边界由浏览器设置,不应手写一个不含边界的 Content-Type;文件选择器可能没有文件,canvas 的 toBlob 也可能得到 null。服务端仍必须核验文件类型、大小、权限与 CSRF。no-cors 只能得到不可读取正文和响应头的 opaque 响应,不是绕过 CORS 的办法。
页面离开不等于数据已经送达。原文的 window.onunload 例子只是历史写法,页面生命周期事件不保证总会触发。keepalive 也有体积限制(RequestInit 文档列出 64 KiB),不适合大文件上传。应按实际浏览器与业务需要设计可靠性和隐私策略,不把统计请求送达视为必然。
完整性校验需要真实摘要。原文 sha256-abcdef 只展示参数形式,不是任何文件的有效已知摘要。应使用可信渠道获得的真实哈希和 HTTPS;完整性参数不能代替来源信任。
取消不是服务端回滚。原文的立即 abort 片段没有消费 fetch 拒绝结果,实际使用应处理 Promise 拒绝。下面的修订版把计时器生命周期和响应体读取一起纳入处理范围;区别是增加状态检查、等待正文并在 finally 清理计时器。
async function fetchWithTimeout(url) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 1000);
try {
const response = await fetch(url, { signal: controller.signal });
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return await response.text();
} catch (error) {
if (error.name === 'AbortError') {
console.log('请求已取消');
}
throw error;
} finally {
clearTimeout(timer);
}
}
取消后服务器可能已接收并处理了请求;支付、创建资源等操作仍须由服务端设计幂等和事务语义,不能把客户端取消当作撤销成功。这里没有访问或测试任何示例接口。
本次校订依据:MDN fetch()、MDN RequestInit、MDN Referrer-Policy。具体浏览器与 Node.js 的网络实现可能存在差异,本文以浏览器上下文为主。












暂无评论内容