Menu

cookies

cookies 是一个异步函数，它允许你在服务端组件中读取 HTTP 传入请求的 cookies，并在服务端操作或路由处理程序中读写传出请求的 cookies。

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

参考

方法

以下方法可用：

方法返回类型描述
get('name')Object接受一个 cookie 名称并返回包含名称和值的对象。
getAll()Array of objects返回所有匹配名称的 cookie 列表。
has('name')Boolean接受一个 cookie 名称并根据 cookie 是否存在返回布尔值。
set(name, value, options)-接受 cookie 名称、值和选项，并设置传出请求的 cookie。
delete(name)-接受一个 cookie 名称并删除该 cookie。
clear()-删除所有 cookies。
toString()String返回 cookies 的字符串表示。

选项

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

选项类型描述
nameString指定 cookie 的名称。
valueString指定要存储在 cookie 中的值。
expiresDate定义 cookie 过期的确切日期。
maxAgeNumber设置 cookie 的生命周期（以秒为单位）。
domainString指定 cookie 可用的域。
pathString将 cookie 的范围限制在域内的特定路径。
secureBoolean确保 cookie 仅通过 HTTPS 连接发送以增加安全性。
httpOnlyBoolean将 cookie 限制为 HTTP 请求，防止客户端访问。
sameSiteBoolean, 'lax', 'strict', 'none'控制 cookie 的跨站请求行为。
priorityString ("low", "medium", "high")指定 cookie 的优先级。
encode('value')Function指定用于编码 cookie 值的函数。
partitionedBoolean指示 cookie 是否分区。

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

值得注意的是

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

示例

获取 cookie

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

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

获取所有 cookies

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

app/page.tsx
TypeScript
import { cookies } from 'next/headers'
 
export default async function Page() {
  const cookieStore = await cookies()
  return cookieStore.getAll().map((cookie) => (
    <div key={cookie.name}>
      <p>名称：{cookie.name}</p>
      <p>值：{cookie.value}</p>
    </div>
  ))
}

设置 cookie

你可以在服务端操作或路由处理程序中使用 cookies().set(name, value, options) 方法设置 cookie。options 对象是可选的。

app/actions.ts
TypeScript
'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: '/',
  })
}
app/actions.js
'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: '/',
  })
}

检查 cookie 是否存在

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

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

删除 cookies

有三种方式可以删除 cookie。

使用 delete() 方法：

app/actions.ts
TypeScript
'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).delete('name')
}
app/actions.js
'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).delete('name')
}

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

app/actions.ts
TypeScript
'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).set('name', '')
}
app/actions.js
'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).set('name', '')
}

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

app/actions.ts
TypeScript
'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).set('name', 'value', { maxAge: 0 })
}
app/actions.js
'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。