Skip to main content

cookies

cookies 函数允许你从 服务器组件 读取 HTTP 传入请求 cookie，或在 服务器动作 或 路由处理程序 中写入传出请求 cookie。

¥The cookies function allows you to read the HTTP incoming request cookies from a Server Component or write outgoing request cookies in a Server Action or Route Handler.

很高兴知道：cookies() 是一个 动态功能，其返回值无法提前得知。在布局或页面中使用它会在请求时选择进入 动态渲染 的路由。

¥Good to know: cookies() is a Dynamic Function whose returned values cannot be known ahead of time. Using it in a layout or page will opt a route into dynamic rendering at request time.

cookies().get(name)​

一种采用 cookie 名称并返回具有名称和值的对象的方法。如果未找到带有 name 的 cookie，则返回 undefined。如果多个 cookie 匹配，则仅返回第一个匹配的。

¥A method that takes a cookie name and returns an object with name and value. If a cookie with name isn't found, it returns undefined. If multiple cookies match, it will only return the first match.

import { cookies } from 'next/headers'

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

cookies().getAll()​

与 get 类似的方法，但返回具有匹配 name 的所有 cookie 的列表。如果未指定 name，则返回所有可用的 cookie。

¥A method that is similar to get, but returns a list of all the cookies with a matching name. If name is unspecified, it returns all the available cookies.

import { cookies } from 'next/headers'

export default function Page() {
  const cookieStore = 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 名称并根据 cookie 是否存在 (true) 或不存在 (false) 返回 boolean。

¥A method that takes a cookie name and returns a boolean based on if the cookie exists (true) or not (false).

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 的方法。

¥A method that takes a cookie name, value, and options and sets the outgoing request cookie.

很高兴知道：HTTP 不允许在流开始后设置 cookie，因此你必须在 服务器动作 或 路由处理程序 中使用 .set()。

¥Good to know: HTTP does not allow setting cookies after streaming starts, so you must use .set() in a Server Action or Route Handler.

'use server'

import { cookies } from 'next/headers'

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

删除 cookies​

¥Deleting cookies

很高兴知道：你只能删除 服务器动作 或 路由处理程序 中的 cookie。

¥Good to know: You can only delete cookies in a Server Action or Route Handler.

有多种删除 cookie 的选项：

¥There are several options for deleting a cookie:

cookies().delete(name)​

你可以显式删除具有给定名称的 cookie。

¥You can explicitly delete a cookie with a given name.

'use server'

import { cookies } from 'next/headers'

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

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

或者，你可以设置一个具有相同名称和空值的新 cookie。

¥Alternatively, you can set a new cookie with the same name and an empty value.

'use server'

import { cookies } from 'next/headers'

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

很高兴知道：.set() 仅适用于 服务器动作 或 路由处理程序。

¥Good to know: .set() is only available in a Server Action or Route Handler.

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

将 maxAge 设置为 0 将使 cookie 立即过期。

¥Setting maxAge to 0 will immediately expire a cookie.

'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 立即过期。

¥Setting expires to any value in the past will immediately expire a cookie.

'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() 的同一域的 cookie。此外，代码必须在与要删除的 cookie 相同的协议（HTTP 或 HTTPS）上执行。

¥Good to know: You can only delete cookies that belong to the same domain from which .set() is called. Additionally, the code must be executed on the same protocol (HTTP or HTTPS) as the cookie you want to delete.

版本历史​

¥Version History

版本变化
v13.0.0cookies 推出。