cookies

cookies 函式允許您從伺服器元件 (Server Component) 讀取 HTTP 傳入請求的 cookies，或在伺服器動作 (Server Action) 或路由處理器 (Route Handler) 中寫入傳出請求的 cookies。

須知：cookies() 是一個動態函式 (Dynamic Function)，其返回值無法預先得知。在佈局或頁面中使用它將會在請求時將路由轉為動態渲染 (dynamic rendering)。

`cookies().get(name)`

此方法接收一個 cookie 名稱並回傳一個包含名稱和值的物件。如果找不到對應名稱的 cookie，則回傳 undefined。如果有多個 cookie 符合，則只會回傳第一個匹配項。

app/page.js

import { cookies } from 'next/headers'

export default function Page() {
  const cookieStore = cookies()
  const theme = cookieStore.get('theme')
  return '...'
}

`cookies().getAll()`

此方法與 get 類似，但會回傳所有符合名稱的 cookies 列表。如果未指定名稱，則會回傳所有可用的 cookies。

app/page.js

import { cookies } from 'next/headers'

export default function Page() {
  const cookieStore = cookies()
  return cookieStore.getAll().map((cookie) => (
    <div key={cookie.name}>
      <p>名稱: {cookie.name}</p>
      <p>值: {cookie.value}</p>
    </div>
  ))
}

`cookies().has(name)`

此方法接收一個 cookie 名稱並根據 cookie 是否存在回傳 boolean 值（存在為 true，否則為 false）。

app/page.js

import { cookies } from 'next/headers'

export default function Page() {
  const cookiesList = cookies()
  const hasCookie = cookiesList.has('theme')
  return '...'
}

`cookies().set(name, value, options)`

此方法接收 cookie 名稱、值和選項，並設定傳出請求的 cookie。

須知：HTTP 不允許在串流開始後設定 cookies，因此您必須在伺服器動作 (Server Action) 或路由處理器 (Route Handler) 中使用 .set()。

app/actions.js

'use server'

import { cookies } from 'next/headers'

async function create(data) {
  cookies().set('name', 'lee')
  // 或
  cookies().set('name', 'lee', { secure: true })
  // 或
  cookies().set({
    name: 'name',
    value: 'lee',
    httpOnly: true,
    path: '/',
  })
}

刪除 cookies

須知：您只能在伺服器動作 (Server Action) 或路由處理器 (Route Handler) 中刪除 cookies。

有以下幾種刪除 cookie 的方式：

`cookies().delete(name)`

您可以明確刪除指定名稱的 cookie。

app/actions.js

'use server'

import { cookies } from 'next/headers'

async function create(data) {
  cookies().delete('name')
}

`cookies().set(name, '')`

或者，您可以設定一個同名但值為空的新 cookie。

app/actions.js

'use server'

import { cookies } from 'next/headers'

async function create(data) {
  cookies().set('name', '')
}

須知：.set() 僅在伺服器動作 (Server Action) 或路由處理器 (Route Handler) 中可用。

`cookies().set(name, value, { maxAge: 0 })`

將 maxAge 設為 0 會立即使 cookie 過期。

app/actions.js

'use server'

import { cookies } from 'next/headers'

async function create(data) {
  cookies().set('name', 'value', { maxAge: 0 })
}

`cookies().set(name, value, { expires: timestamp })`

將 expires 設為過去的任何時間戳會立即使 cookie 過期。

app/actions.js

'use server'

import { cookies } from 'next/headers'

async function create(data) {
  const oneDay = 24 * 60 * 60 * 1000
  cookies().set('name', 'value', { expires: Date.now() - oneDay })
}

須知：您只能刪除與呼叫 .set() 的來源相同網域的 cookies。此外，程式碼必須在與要刪除的 cookie 相同的協議（HTTP 或 HTTPS）上執行。

版本歷史

版本	變更內容
`v13.0.0`	引入 `cookies`。

On this page