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()`