logoNext.js 繁體中文
文件部落格學習
介紹/API 參考文檔/函式/cookies

cookies

cookies 是一个异步函数，允许您在伺服器组件 (Server Components) 中读取 HTTP 传入请求的 cookies，并在伺服器动作 (Server Actions) 或路由处理器 (Route Handlers) 中读取/写入传出请求的 cookies。

import { cookies } from 'next/headers'

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

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

参考

方法

以下方法可用：

方法返回类型描述
get('name')物件接受 cookie 名称并返回包含名称和值的物件。
getAll()物件数组返回所有匹配名称的 cookies 列表。
has('name')布尔值接受 cookie 名称并返回该 cookie 是否存在的布尔值。
set(name, value, options)-接受 cookie 名称、值和选项，并设置传出请求的 cookie。
delete(name)-接受 cookie 名称并删除该 cookie。
clear()-删除所有 cookies。
toString()字符串返回 cookies 的字符串表示形式。

选项

设置 cookie 时，options 物件支持以下属性：

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

唯一具有默认值的选项是 path。

要了解更多关于这些选项的信息，请参阅 MDN 文档。

须知

  • cookies 是一个异步函数，返回一个 Promise。您必须使用 async/await 或 React 的 use 函数来访问 cookies。
    • 在版本 14 及更早版本中，cookies 是一个同步函数。为了向后兼容，您仍然可以在 Next.js 15 中同步访问它，但此行为将在未来被弃用。
  • cookies 是一个动态 API (Dynamic API)，其返回值无法提前预知。在布局或页面中使用它将使路由选择动态渲染 (dynamic rendering)。
  • .delete 方法只能在以下情况下调用：
  • HTTP 不允许在流式传输开始后设置 cookies，因此您必须在伺服器动作 (Server Action) 或路由处理器 (Route Handler) 中使用 .set。

在伺服器组件中使用 cookies 时，重要的是要理解 cookies 本质上是客户端存储机制：

  • 读取 cookies 在伺服器组件中有效，因为您访问的是客户端浏览器在 HTTP 请求标头中发送到伺服器的 cookie 数据。
  • 设置 cookies 不能直接在伺服器组件中完成，即使使用路由处理器或伺服器动作也是如此。这是因为 cookies 实际上是由浏览器存储的，而不是伺服器。

伺服器只能发送指令（通过 Set-Cookie 标头）告诉浏览器存储 cookies - 实际的存储发生在客户端。这就是为什么修改状态的操作（.set、.delete、.clear）必须在可以正确设置响应标头的路由处理器或伺服器动作中执行。

示例

您可以使用 (await cookies()).get('name') 方法获取单个 cookie：

import { cookies } from 'next/headers'

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

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

获取所有 cookies

您可以使用 (await cookies()).getAll() 方法获取所有匹配名称的 cookies。如果未指定 name，则返回所有可用的 cookies。

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

您可以在伺服器动作 (Server Action) 或路由处理器 (Route Handler) 中使用 (await cookies()).set(name, value, options) 方法设置 cookie。options 物件 是可选的。

'use server'

import { cookies } from 'next/headers'

export async function create(data) {
  const cookieStore = await cookies()

  cookieStore.set('name', 'lee')
  // 或
  cookieStore.set('name', 'lee', { secure: true })
  // 或
  cookieStore.set({
    name: 'name',
    value: 'lee',
    httpOnly: true,
    path: '/',
  })
}
'use server'

import { cookies } from 'next/headers'

export async function create(data) {
  const cookieStore = await cookies()

  cookieStore.set('name', 'lee')
  // 或
  cookieStore.set('name', 'lee', { secure: true })
  // 或
  cookieStore.set({
    name: 'name',
    value: 'lee',
    httpOnly: true,
    path: '/',
  })
}

您可以使用 (await cookies()).has(name) 方法检查 cookie 是否存在：

import { cookies } from 'next/headers'

export default async function Page() {
  const cookieStore = await cookies()
  const hasCookie = cookieStore.has('theme')
  return '...'
}
import { cookies } from 'next/headers'

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

删除 cookies

有三种方法可以删除 cookie。

使用 delete() 方法：

'use server'

import { cookies } from 'next/headers'

export async function delete(data) {
  (await cookies()).delete('name')
}
'use server'

import { cookies } from 'next/headers'

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

设置一个具有相同名称和空值的新 cookie：

'use server'

import { cookies } from 'next/headers'

export async function delete(data) {
  (await cookies()).set('name', '')
}
'use server'

import { cookies } from 'next/headers'

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

将 maxAge 设置为 0 将立即使 cookie 过期。maxAge 接受以秒为单位的值。

'use server'

import { cookies } from 'next/headers'

export async function delete(data) {
  (await cookies()).set('name', 'value', { maxAge: 0 })
}
'use server'

import { cookies } from 'next/headers'

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

版本历史

版本变更
v15.0.0-RCcookies 现在是一个异步函数。提供了代码修改工具 (codemod)。
v13.0.0引入 cookies。

connection

關於 `connection` 函式的 API 參考文件。

draftMode

關於 draftMode 函式的 API 參考文件。