跳至内容
API 参考函数cookie

cookie

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 的字符串表示形式。

选项

设置 cookie 时，支持 options 对象中的以下属性

选项类型描述
名称字符串指定 cookie 的名称。
值字符串指定要存储在 cookie 中的值。
过期时间日期定义 cookie 过期的确切日期。
maxAge数字以秒为单位设置 cookie 的生命周期。
域名字符串指定 cookie 可用的域名。
路径字符串将 cookie 的范围限制到域名内的特定路径。
安全布尔值，确保 cookie 仅通过 HTTPS 连接发送，以增强安全性。
httpOnly布尔值将 cookie 限制为 HTTP 请求，防止客户端访问。
sameSite布尔值、'lax'、'strict'、'none'控制 cookie 的跨站点请求行为。
优先级字符串（"low"、"medium"、"high"）指定 cookie 的优先级
encode('value')函数指定一个将用于对 cookie 值进行编码的函数。
分区布尔值指示 cookie 是否已 分区。

要详细了解这些选项，请参阅 MDN 文档。

了解详情

  • cookies 是一个 **异步** 函数，它返回一个 Promise。您必须使用 async/await 或 React 的 use 函数来访问 cookie。
    • 在版本 14 及更早版本中，cookies 是一个同步函数。为了帮助实现向后兼容性，您仍然可以在 Next.js 15 中同步访问它，但此行为将在将来弃用。
  • cookies 是一个 动态 API，其返回值无法提前知道。在布局或页面中使用它将使路由进入 动态渲染 模式。
  • .delete 方法只能在以下场景中调用：
    • 在 服务器操作 或 路由处理程序 中。
    • 如果它属于与调用 .set 的域名相同的域名。此外，代码必须在与要删除的 Cookie 相同的协议（HTTP 或 HTTPS）上执行。
  • HTTP 不允许在流开始后设置 Cookie，因此必须在 服务器操作 或 路由处理程序 中使用 .set。

示例

可以使用 cookies().get('name') 方法获取单个 Cookie。

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

获取所有 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().set(name, value, options) 方法设置 Cookie。 options 对象 是可选的。

app/actions.ts
'use server'
 
import { cookies } from 'next/headers'
 
export async function create(data) {
  const cookieStore = await cookies()
 
  cookieStore().set('name', 'lee')
  // or
  cookieStore().set('name', 'lee', { secure: true })
  // or
  cookieStore().set({
    name: 'name',
    value: 'lee',
    httpOnly: true,
    path: '/',
  })
}

可以使用 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。