JavaScript Fetch API 使用详解：从基础到高级应用

作者：闭包旅人时间：2026-10-25 11:08:17浏览：243

本文深入解析 JavaScript Fetch API，涵盖其基本用法、与 XMLHttpRequest 的区别、请求参数配置（如 credentials 和 method）、Body 数据处理（JSON 与 FormData）、Headers 及 Response 对象属性，以及 Service Workers 中的特殊应用。

Fetch API 提供了用于访问和操作 HTTP 管道的 JavaScript 接口，包括请求和响应对象。它还提供了一个全局 fetch() 方法，该方法提供了一种简单且合理的方式来跨网络异步获取资源。

此类功能此前通常由 XMLHttpRequest 实现。Fetch 提供了更优越的替代方案，易于被其他技术集成，例如 Service Workers。此外，Fetch 还为 CORS 和 HTTP 扩展等 HTTP 相关概念提供了统一的逻辑定义点。

需注意，fetch 规范与 jQuery.ajax() 主要有两种差异，请牢记：

当接收到代表错误的 HTTP 状态码时，从 fetch() 返回的 Promise 不会被标记为 reject，即使该 HTTP 响应的状态码是 404 或 500。相反，它会将 Promise 状态标记为 resolve（但会将 resolve 的返回值的 ok 属性设置为 false），仅当网络故障或请求被阻止时，才会标记为 reject。
默认情况下，fetch 不会从服务端发送或接收任何 cookies。如果站点依赖于用户 session，这会导致未经认证的请求（要发送 cookies，必须设置 credentials 选项）。自 2017 年 8 月 25 日起，默认的 credentials 政策变更为 same-origin，Firefox 也在 61.0b13 中更改了默认值。

进行 fetch 请求

一个基本的 fetch 请求设置起来很简单。看看下面的代码：

fetch('http://example.com/movies.json')
  .then(function(response) {
    return response.json();
  })
  .then(function(myJson) {
    console.log(myJson);
  });

这里我们通过网络获取一个 JSON 文件并将其打印到控制台。最简单的用法是只提供一个参数用来指明想 fetch() 到的资源路径，然后返回一个包含响应结果的 promise（一个 Response 对象）。

当然它只是一个 HTTP 响应，而不是真的 JSON。为了获取 JSON 的内容，我们需要使用 json() 方法（在 Body mixin 中定义，被 Request 和 Response 对象实现）。

注意：Body mixin 还有其他相似的方法，用于获取其他类型的内容。参考 Body。

最好使用符合内容安全策略 (CSP) 的链接而不是使用直接指向资源地址的方式来进行 Fetch 的请求。

支持的请求参数

fetch() 接受第二个可选参数，一个可以控制不同配置的 init 对象：

参考 fetch()，查看所有可选的配置和更多描述。

// Example POST method implementation:

postData('http://example.com/answer', {answer: 42})
  .then(data => console.log(data)) // JSON from `response.json()` call
  .catch(error => console.error(error))

function postData(url, data) {
  // Default options are marked with *
  return fetch(url, {
    body: JSON.stringify(data), // must match 'Content-Type' header
    cache: 'no-cache', // *default, no-cache, reload, force-cache, only-if-cached
    credentials: 'same-origin', // include, same-origin, *omit
    headers: {
      'user-agent': 'Mozilla/4.0 MDN Example',
      'content-type': 'application/json'
    },
    method: 'POST', // *GET, POST, PUT, DELETE, etc.
    mode: 'cors', // no-cors, cors, *same-origin
    redirect: 'follow', // manual, *follow, error
    referrer: 'no-referrer', // *client, no-referrer
  })
  .then(response => response.json()) // parses response to JSON
}

发送带凭据的请求

为了让浏览器发送包含凭据的请求（即使是跨域源），要将 credentials: 'include' 添加到传递给 fetch() 方法的 init 对象。

fetch('https://example.com', {
  credentials: 'include'  
})

如果你只想在请求 URL 与调用脚本位于同一起源处时发送凭据，请添加 credentials: 'same-origin'。

// The calling script is on the origin 'https://example.com'

fetch('https://example.com', {
  credentials: 'same-origin'  
})

要改为确保浏览器不在请求中包含凭据，请使用 credentials: 'omit'。

fetch('https://example.com', {
  credentials: 'omit'  
})

上传 JSON 数据

使用 fetch() POST JSON 数据

var url = 'https://example.com/profile';
var data = {username: 'example'};

fetch(url, {
  method: 'POST', // or 'PUT'
  body: JSON.stringify(data), // data can be `string` or {object}!
  headers: new Headers({
    'Content-Type': 'application/json'
  })
}).then(res => res.json())
.catch(error => console.error('Error:', error))
.then(response => console.log('Success:', response));

上传文件

可以通过 HTML <input type="file" /> 元素，FormData() 和 fetch() 上传文件。

var formData = new FormData();
var fileField = document.querySelector("input[type='file']");

formData.append('username', 'abc123');
formData.append('avatar', fileField.files[0]);

fetch('https://example.com/profile/avatar', {
  method: 'PUT',
  body: formData
})
.then(response => response.json())
.catch(error => console.error('Error:', error))
.then(response => console.log('Success:', response));

上传多个文件

可以通过 HTML <input type="file" mutiple/> 元素，FormData() 和 fetch() 上传文件。

var formData = new FormData();
var photos = document.querySelector("input[type='file'][multiple]");

formData.append('title', 'My Vegas Vacation');
formData.append('photos', photos.files);

fetch('https://example.com/posts', {
  method: 'POST',
  body: formData
})
.then(response => response.json())
.then(response => console.log('Success:', JSON.stringify(response)))
.catch(error => console.error('Error:', error));

检测请求是否成功

如果遇到网络故障，fetch() promise 将会 reject，带上一个 TypeError 对象。虽然这个情况经常是遇到了权限问题或类似问题——比如 404 不是一个网络故障。想要精确的判断 fetch() 是否成功，需要包含 promise resolved 的情况，此时再判断 Response.ok 是不是为 true。类似以下代码：

fetch('flowers.jpg').then(function(response) {
  if(response.ok) {
    return response.blob();
  }
  throw new Error('Network response was not ok.');
}).then(function(myBlob) { 
  var objectURL = URL.createObjectURL(myBlob); 
  myImage.src = objectURL; 
}).catch(function(error) {
  console.log('There has been a problem with your fetch operation: ', error.message);
});

自定义请求对象

除了传给 fetch() 一个资源的地址，你还可以通过使用 Request() 构造函数来创建一个 request 对象，然后再作为参数传给 fetch()：

var myHeaders = new Headers();

var myInit = { method: 'GET',
               headers: myHeaders,
               mode: 'cors',
               cache: 'default' };

var myRequest = new Request('flowers.jpg', myInit);

fetch(myRequest).then(function(response) {
  return response.blob();
}).then(function(myBlob) {
  var objectURL = URL.createObjectURL(myBlob);
  myImage.src = objectURL;
});

Request() 和 fetch() 接受同样的参数。你甚至可以传入一个已存在的 request 对象来创造一个拷贝：

var anotherRequest = new Request(myRequest,myInit);

这个很有用，因为 request 和 response bodies 只能被使用一次（译者注：这里的意思是因为设计成了 stream 的方式，所以它们只能被读取一次）。创建一个拷贝就可以再次使用 request/response 了，当然也可以使用不同的 init 参数。

注意：clone() 方法也可以用于创建一个拷贝。它在语义上有一点不同于其他拷贝的方法。其他方法（比如拷贝一个 response）中，如果 request 的 body 已经被读取过，那么将执行失败，然而 clone() 则不会失败。

Headers

使用 Headers 的接口，你可以通过 Headers() 构造函数来创建一个你自己的 headers 对象。一个 headers 对象是一个简单的多名值对：

var content = "Hello World";
var myHeaders = new Headers();
myHeaders.append("Content-Type", "text/plain");
myHeaders.append("Content-Length", content.length.toString());
myHeaders.append("X-Custom-Header", "ProcessThisImmediately");

也可以传一个多维数组或者对象字面量：

myHeaders = new Headers({
  "Content-Type": "text/plain",
  "Content-Length": content.length.toString(),
  "X-Custom-Header": "ProcessThisImmediately",
});

它的内容可以被获取：

console.log(myHeaders.has("Content-Type")); // true
console.log(myHeaders.has("Set-Cookie")); // false
myHeaders.set("Content-Type", "text/html");
myHeaders.append("X-Custom-Header", "AnotherValue");

console.log(myHeaders.get("Content-Length")); // 11
console.log(myHeaders.getAll("X-Custom-Header")); // ["ProcessThisImmediately", "AnotherValue"]

myHeaders.delete("X-Custom-Header");
console.log(myHeaders.getAll("X-Custom-Header")); // [ ]

虽然一些操作只能在 ServiceWorkers 中使用，但是它提供了更方便的操作 Headers 的 API。

如果使用了一个不合法的 HTTP Header 属性名，那么 Headers 的方法通常都抛出 TypeError 异常。如果不小心写入了一个不可写的属性，也会抛出一个 TypeError 异常。除此以外的情况，失败了并不抛出异常。例如：

var myResponse = Response.error();
try {
  myResponse.headers.set("Origin", "http://mybank.com");
} catch(e) {
  console.log("Cannot pretend to be a bank!");
}

最佳实践是在使用之前检查 content type 是否正确，比如：

fetch(myRequest).then(function(response) {
  if(response.headers.get("content-type") === "application/json") {
    return response.json().then(function(json) {
      // process your JSON further
    });
  } else {
    console.log("Oops, we haven't got JSON!");
  }
});

Guard

由于 Headers 可以在 request 请求中被发送或者在 response 请求中被接收，并且规定了哪些参数是可写的，Headers 对象有一个特殊的 guard 属性。这个属性没有暴露给 Web，但是它影响到哪些内容可以在 Headers 对象中被操作。

可能的值如下：

none：默认的
request：从 request 中获得的 headers（Request.headers）只读
request-no-cors：从不同域（Request.mode no-cors）的 request 中获得的 headers 只读
response：从 response 中获得的 headers（Response.headers）只读
immutable：在 ServiceWorkers 中最常用的，所有的 headers 都只读。

注意：你不可以添加或者修改一个 guard 属性是 request 的 Request Headers 的 Content-Length 属性。同样地，插入 Set-Cookie 属性到一个 response headers 是不允许的，因此 ServiceWorkers 是不能给合成的 Response 的 headers 添加一些 cookies。

Response 对象

如上述, Response 实例是在 fetch() 处理完 promises 之后返回的。

你会用到的最常见的 response 属性有:

Response.status — 整数 (默认值为 200) 为 response 的状态码.
Response.statusText — 字符串 (默认值为"OK"), 该值与 HTTP 状态码消息对应.
Response.ok — 如上所示, 该属性是来检查 response 的状态是否在 200-299 (包括 200, 299) 这个范围内. 该属性返回一个 Boolean 值.

它的实例也可用通过 JavaScript 来创建, 但只有在 ServiceWorkers 中才真正有用, 当使用 respondWith() 方法并提供了一个自定义的 response 来接受 request 时:

var myBody = new Blob();

addEventListener('fetch', function(event) {
  event.respondWith(new Response(myBody, {
    headers: { "Content-Type" : "text/plain" }
  });
});

Response() 构造方法接受两个可选参数—response 的数据体和一个初始化对象 (与 Request() 所接受的 init 参数类似.)

注意: 静态方法 error() 只是返回了一个错误的 response. 与此类似地, redirect() 只是返回了一个可以重定向至某 URL 的 response. 这些也只与 Service Workers 才有关。

Body

不管是请求还是响应都能够包含 body 对象. body 也可以是以下任意类型的实例.

ArrayBuffer
ArrayBufferView (Uint8Array 等)
Blob/File
string
URLSearchParams
[FormData]("FormData 接口提供了一种表示表单数据的键值对的构造方式，经过它的数据可以使用 XMLHttpRequest.send() 方法送出，本接口和此方法都相当简单直接。如果送出时的编码类型被设为 "multipart/form-data"，它会使用和表单一样的格式。")

Body 类定义了以下方法 (这些方法都被 Request 和 Response 所实现) 以获取 body 内容. 这些方法都会返回一个被解析后的 Promise 对象和数据.

arrayBuffer()
blob()
json()
[text()]("Body混入的 text() 方法提供了一个可供读取的"返回流", ——它返回一个包含USVString对象 (text)的Promise对象，返回结果的编码为UTF-8。")
formData()

比起 XHR 来，这些方法让非文本化的数据使用起来更加简单。

请求体可以由传入 body 参数来进行设置:

var form = new FormData(document.getElementById('login-form'));
fetch("/login", {
  method: "POST",
  body: form
})

request 和 response（包括 fetch() 方法）都会试着自动设置 Content-Type。如果没有设置 Content-Type 值，发送的请求也会自动设值。

特性检测

Fetch API 的支持情况，可以通过检测 Headers, Request, Response 或 fetch() 是否在 Window 或 Worker 域中。例如：

if(self.fetch) {
    // run my fetch request here
} else {
    // do something with XMLHttpRequest?
}

到此这篇关于 JavaScript 使用 Fetch 的方法详解的文章就介绍到这了, 更多相关 JavaScript Fetch 内容请搜索本站以前的文章或继续浏览下面的相关文章希望大家以后多多支持本站！

作者最新文章

什么时候该用JS构造器：与工厂模式、字面量的选择对比

2026-11-05 16:18:22

推荐几款轻量级JS照片墙开源库及对比

2026-11-05 15:56:19

JavaScript递归写法有哪些常见陷阱及避免方法

2026-11-05 14:53:38

JS数组浅拷贝与深拷贝怎么选？场景与方法总结

2026-11-05 14:41:02

p5.js 中 setup() 和 draw() 函数的执行机制详解

2026-11-05 12:32:38