cookies

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

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

`cookies().get(name)`

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

app/page.js

import { cookies } from 'next/headers'

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

`cookies().getAll()`

此方法與 get 類似，但會回傳所有符合 name 的 cookies 列表。若未指定 name，則回傳所有可用的 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 cookieStore = cookies()
  const hasCookie = cookieStore.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 delete(data) {
  cookies().delete('name')
}

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

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

app/actions.js

'use server'

import { cookies } from 'next/headers'

async function delete(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 delete(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 delete(data) {
  const oneDay = 24 * 60 * 60 * 1000
  cookies().set('name', 'value', { expires: Date.now() - oneDay })
}

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

版本歷史

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

伺服器動作與資料異動

學習如何使用 Next.js 處理表單提交與資料異動

伺服器動作與資料異動

On this page