跳至內容
API 參考函式cookies

cookies

cookies 是一個非同步函式，允許您在 伺服器組件 中讀取 HTTP 傳入請求的 Cookie，並在 伺服器動作 或 路由處理器 中讀取/寫入傳出請求的 Cookie。

app/page.tsx
import { cookies } from 'next/headers'
 
export default async function Page() {
  const cookieStore = await cookies()
  const theme = cookieStore.get('theme')
  return '...'
}

參考

方法

以下方法可用：

方法回傳類型說明
get('name')物件接受 cookie 名稱並回傳包含名稱和值的物件。
getAll()物件陣列回傳所有名稱相符的 cookie 列表。
has('name')布林值接受 cookie 名稱並根據 cookie 是否存在回傳布林值。
set(name, value, options)-接受 cookie 名稱、值和選項，並設定送出的請求 cookie。
delete(name)-接受 cookie 名稱並刪除 cookie。
clear()-刪除所有 cookie。
toString()字串回傳 cookie 的字串表示形式。

選項
選項類型說明
name字串指定 cookie 的名稱。
value字串指定要儲存在 cookie 中的值。
expires日期定義 cookie 的確切到期日期。
maxAge數字以秒為單位設定 cookie 的生命週期。
domain字串指定 cookie 可用的網域。
path字串將 cookie 的範圍限制在網域內的特定路徑。
secure布林值確保 cookie 僅透過 HTTPS 連線傳送，以增強安全性。
httpOnly布林值將 cookie 限制為 HTTP 請求，防止用戶端存取。
sameSite布林值、'lax'、'strict'、'none'控制 cookie 的跨網站請求行為。
priority字串 ("low"、"medium"、"high")指定 cookie 的優先順序
encode('value')函式指定用於編碼 cookie 值的函式。
partitioned布林值指出 cookie 是否已分區。

要瞭解更多關於這些選項的資訊，請參閱 MDN 文件。

注意事項

  • cookies 是一個非同步函式，它會回傳一個 promise。您必須使用 async/await 或 React 的 use 函式來存取 cookies。
    • 在版本 14 以及更早的版本中，cookies 是一個同步函式。為了幫助向下相容，您仍然可以在 Next.js 15 中以同步方式存取它，但此行為將在未來版本中被棄用。
  • cookies 是一個動態 API，其回傳值無法事先得知。在佈局或頁面中使用它會將路由選擇為動態渲染。
  • .delete 方法只能在
    • 伺服器動作 或 路由處理程式 中呼叫。
    • 如果它屬於與呼叫 .set 的網域相同，此外，程式碼必須在與您要刪除的 cookie 相同的協定 (HTTP 或 HTTPS) 上執行。
  • HTTP 不允許在串流開始後設定 cookie，因此您必須在 伺服器動作 或 路由處理程式 中使用 .set。

範例

取得所有 Cookie

您可以使用 cookies().getAll() 方法來取得所有符合名稱的 Cookie。如果未指定 name，它會傳回所有可用的 Cookie。

app/page.tsx
import { cookies } from 'next/headers'
 
export default async function Page() {
  const cookieStore = await cookies()
  return cookieStore.getAll().map((cookie) => (
    <div key={cookie.name}>
      <p>Name: {cookie.name}</p>
      <p>Value: {cookie.value}</p>
    </div>
  ))
}

您可以使用 cookies().has(name) 方法來檢查 Cookie 是否存在。

app/page.ts
import { cookies } from 'next/headers'
 
export default async function Page() {
  const cookieStore = await cookies()
  const hasCookie = cookieStore.has('theme')
  return '...'
}

刪除 Cookie

您可以透過三種方式刪除 Cookie。

使用 delete() 方法

app/actions.ts
'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).delete('name')
}

使用相同的名稱和空值設定新的 Cookie

app/actions.ts
'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).set('name', '')
}

將 maxAge 設定為 0 將立即使 Cookie 過期。maxAge 接受以秒為單位的數值。

app/actions.ts
'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).set('name', 'value', { maxAge: 0 })
}

版本歷史記錄

版本變更
v15.0.0-RCcookies 現在是一個非同步函式。 提供了程式碼轉換器。
v13.0.0引進 cookies。