RequestInit

Fetch API 的 RequestInit 字典表示可用于配置 fetch 请求的一组选项。

你可以将 RequestInit 对象传递给 Request() 构造函数，或直接传递给 fetch() 函数调用。

你还可以使用 RequestInit 构造一个 Request，然后将该 Request 与另一个 RequestInit 一起传递给 fetch() 调用。如果你这样做，并且在两个地方都设置了相同的选项，那么将使用直接传递给 fetch() 的值。

实例属性

attributionReporting 可选实验性

指示你希望请求的响应能够注册基于 JavaScript 的归因源或归因触发器。attributionReporting 是一个包含以下属性的对象：

eventSourceEligible: 一个布尔值。如果设置为 true，则请求的响应有资格注册归因源。如果设置为 false，则无资格。
triggerEligible: 一个布尔值。如果设置为 true，则请求的响应有资格注册归因触发器。如果设置为 false，则无资格。

有关更多详细信息，请参阅归因报告 API。

body 可选

请求正文包含要发送到服务器的内容，例如在 POST 或 PUT 请求中。它被指定为以下任意类型的一个实例：

有关更多详细信息，请参阅设置正文。

browsingTopics 可选实验性

一个布尔值，指定是否应在相关请求中以 Sec-Browsing-Topics 标头发送当前用户的选定主题。

有关更多详细信息，请参阅使用 Topics API。

cache 可选

你希望用于请求的缓存模式。它可以是以下值之一：

default

浏览器在其 HTTP 缓存中查找与请求匹配的响应。

如果存在匹配项且它新鲜，则将从缓存中返回。
如果存在匹配项但它陈旧，浏览器将向远程服务器发出条件请求。如果服务器指示资源未更改，则将从缓存中返回。否则，将从服务器下载资源并更新缓存。
如果没有匹配项，浏览器将发出正常请求，并使用下载的资源更新缓存。

no-store

浏览器从远程服务器获取资源，不先查找缓存，并且不会使用下载的资源更新缓存。

reload

浏览器从远程服务器获取资源，不先查找缓存，但随后会使用下载的资源更新缓存。

no-cache

浏览器在其 HTTP 缓存中查找与请求匹配的响应。

如果存在匹配项，无论是新鲜的还是陈旧的，浏览器都将向远程服务器发出条件请求。如果服务器指示资源未更改，则将从缓存中返回。否则，将从服务器下载资源并更新缓存。
如果没有匹配项，浏览器将发出正常请求，并使用下载的资源更新缓存。

force-cache

浏览器在其 HTTP 缓存中查找与请求匹配的响应。

如果存在匹配项，无论是新鲜的还是陈旧的，都将从缓存中返回。
如果没有匹配项，浏览器将发出正常请求，并使用下载的资源更新缓存。

only-if-cached

浏览器在其 HTTP 缓存中查找与请求匹配的响应。实验性

如果存在匹配项，无论是新鲜的还是陈旧的，都将从缓存中返回。
如果没有匹配项，则返回网络错误。

"only-if-cached" 模式只能在请求的mode 为 "same-origin" 时使用。如果请求的 redirect 属性为 "follow" 并且重定向不违反 "same-origin" 模式，则将遵循缓存的重定向。

credentials 可选

控制浏览器是否随请求发送凭据，以及是否遵守任何 Set-Cookie 响应头。凭据可以是 cookie、TLS 客户端证书或包含用户名和密码的身份验证头。此选项可以是以下值之一：

omit: 从不在请求中发送凭据或在响应中包含凭据。
same-origin: 仅为同源请求发送和包含凭据。
include: 始终包含凭据，即使是跨域请求。

在跨域请求中包含凭据可能会使站点容易受到 CSRF 攻击，因此即使 credentials 设置为 include，服务器也必须通过在其响应中包含 Access-Control-Allow-Credentials 来同意包含它们。此外，在这种情况下，服务器必须在 Access-Control-Allow-Origin 响应头中明确指定客户端的源（即不允许使用 *）。

有关更多详细信息，请参阅包含凭据。

默认为 same-origin。

duplex 可选实验性

控制请求的双工行为。如果存在此项，则其值必须为 half，这意味着浏览器必须在处理响应之前发送整个请求。

当body是ReadableStream时，此选项必须存在。

headers 可选

你希望添加到请求的任何标头，包含在 Headers 对象中，或包含在键为标头名称、值为标头值的对象字面量中。

许多标头由浏览器自动设置，不能由脚本设置：这些标头称为禁止请求标头。

如果 mode 选项设置为 no-cors，则你只能设置 CORS 安全列表请求标头。

有关更多详细信息，请参阅设置标头。

integrity 可选

包含请求的子资源完整性值。

在获取资源时将对其进行检查，就像在 <script> 元素上设置 integrity 属性时一样。浏览器将使用指定的算法计算获取资源的哈希值，如果结果与指定值不匹配，浏览器将拒绝该 fetch 请求并返回网络错误。

此选项的格式为 <hash-algo>-<hash-source>，其中：

<hash-algo> 是以下值之一：sha256、sha384 或 sha512
<hash-source> 是使用指定哈希算法对资源进行哈希处理的结果的 Base64 编码。

默认为空字符串。

keepalive 可选

一个布尔值。当设置为 true 时，如果发起请求的页面在请求完成之前被卸载，浏览器将不会中止关联的请求。这使得 fetch() 请求即使在用户离开或关闭页面后也能在会话结束时发送分析数据。

与为此目的使用 Navigator.sendBeacon() 相比，这有一些优势。例如，你可以使用 POST 以外的 HTTP 方法，自定义请求属性，并通过 fetch Promise 实现访问服务器响应。它也在 Service Workers 中可用。

keepalive 请求的正文大小限制为 64 kibibytes。

默认为 false。

默认为 GET。

设置请求的跨域行为。以下值之一：

不允许跨域请求。如果向不同来源发送 same-origin 请求，结果是网络错误。

cors

如果请求是跨域的，则它将使用跨域资源共享 (CORS) 机制。响应中仅暴露 CORS 安全列表响应标头。

no-cors

对跨域请求禁用 CORS。此选项具有以下限制：

方法只能是 HEAD、GET 或 POST 之一。
标头只能是 CORS 安全列表请求标头，并且附加限制是 Range 标头也不允许。这同样适用于服务工作线程添加的任何标头。
响应是不透明的，这意味着它的标头和正文对 JavaScript 不可用，并且它的状态码始终为 0。

no-cors 的主要应用场景是 Service Worker：尽管 no-cors 请求的响应不能被 JavaScript 读取，但它可以被 Service Worker 缓存，然后用作拦截到的 fetch 请求的响应。请注意，在这种情况下，你不知道请求是否成功，因此你应该采用一种缓存策略，允许缓存的响应从网络更新（例如缓存优先并刷新缓存）。

navigate

仅用于 HTML 导航。navigate 请求仅在文档之间导航时创建。

有关更多详细信息，请参阅发起跨域请求。

默认为 cors。

priority 可选

指定 fetch 请求相对于相同类型其他请求的优先级。必须是以下值之一：

high: 相对于相同类型其他请求的较高优先级 fetch 请求。
low: 相对于相同类型其他请求的较低优先级 fetch 请求。
auto: 用户对 fetch 优先级没有偏好。如果未设置值或设置了无效值，则使用此值。

默认为 auto。

redirect 可选

决定浏览器在服务器回复重定向状态时的行为。以下值之一：

follow: 自动跟随重定向。
error: 当返回重定向状态时，以网络错误拒绝 Promise。
manual: 返回一个几乎所有字段都被过滤掉的响应，以便服务工作线程可以存储响应并稍后重放。

默认为 follow。

referrer 可选

一个字符串，指定用于请求的 Referer 标头的值。以下值之一：

同源相对或绝对 URL: 将 Referer 标头设置为给定值。相对 URL 相对于发起请求的页面 URL 解析。
空字符串: 省略 Referer 标头。
about:client: 将 Referer 标头设置为请求上下文的默认值（例如，发起请求的页面的 URL）。

默认为 about:client。

referrerPolicy 可选

一个字符串，用于设置 Referer 标头的策略。此选项的语法和语义与 Referrer-Policy 标头完全相同。

signal 可选

一个 AbortSignal。如果设置此选项，可以通过调用相应 AbortController 上的 abort() 来取消请求。

示例

将选项传递给 `fetch()`

在此示例中，我们将 method、body 和 headers 选项直接传递给 fetch() 方法调用：

async function post() {
  const response = await fetch("https://example.org/post", {
    method: "POST",
    body: JSON.stringify({ username: "example" }),
    headers: {
      "Content-Type": "application/json",
    },
  });

  console.log(response.status);
}

将选项传递给 `Request()` 构造函数

在此示例中，我们创建一个 Request，将其构造函数传递相同的选项集，然后将请求传递给 fetch()：

async function post() {
  const request = new Request("https://example.org/post", {
    method: "POST",
    body: JSON.stringify({ username: "example" }),
    headers: {
      "Content-Type": "application/json",
    },
  });

  const response = await fetch(request);

  console.log(response.status);
}

将选项同时传递给 `Request()` 和 `fetch()`

在此示例中，我们创建一个 Request，将其构造函数传递 method、headers 和 body 选项。然后，我们将请求以及 body 和 referrer 选项传递给 fetch()：

async function post() {
  const request = new Request("https://example.org/post", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ username: "example1" }),
  });

  const response = await fetch(request, {
    body: JSON.stringify({ username: "example2" }),
    referrer: "",
  });

  console.log(response.status);
}

在这种情况下，请求将使用以下选项发送：

method: "POST"
headers: {"Content-Type": "application/json"}
body: '{"username":"example2"}'
referrer: ""

规范

规范
Fetch # requestinit

另见

帮助改进 MDN

了解如何贡献

本页面最后由 MDN 贡献者在 2025 年 8 月 19 日修改。

在 GitHub 上查看此页面 • 报告此内容的问题

RequestInit

实例属性

示例

将选项传递给 fetch()

将选项传递给 Request() 构造函数

将选项同时传递给 Request() 和 fetch()

规范

另见

帮助改进 MDN

将选项传递给 `fetch()`

将选项传递给 `Request()` 构造函数

将选项同时传递给 `Request()` 和 `fetch()`