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 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