cookies

cookies 是一个异步函数，允许你在 Server Components 中读取 HTTP 传入请求的 cookies，并在 Server Actions 或 Route Handlers 中读取/写入传出请求的 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 '...'
}

参考

方法

以下方法可用：

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

选项

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

选项	类型	描述
`name`	String	指定 cookie 的名称。
`value`	String	指定要存储在 cookie 中的值。
`expires`	Date	定义 cookie 过期的确切日期。
`maxAge`	Number	设置 cookie 的生命周期（以秒为单位）。
`domain`	String	指定 cookie 可用的域。
`path`	String，默认值：`'/'`	将 cookie 的作用域限制为域内的特定路径。
`secure`	Boolean	确保 cookie 仅通过 HTTPS 连接发送，以增强安全性。
`httpOnly`	Boolean	将 cookie 限制为 HTTP 请求，防止客户端访问。
`sameSite`	Boolean，`'lax'`，`'strict'`，`'none'`	控制 cookie 的跨站点请求行为。
`priority`	String（`"low"`，`"medium"`，`"high"`）	指定 cookie 的优先级。
`partitioned`	Boolean	指示 cookie 是否为分区的。

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

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

值得注意的是

cookies 是一个异步函数，返回一个 promise。你必须使用 async/await 或 React 的 use 函数来访问 cookies。
- 在版本 14 及更早版本中，cookies 是一个同步函数。为了帮助向后兼容，你仍然可以在 Next.js 15 中同步访问它，但这种行为将在未来被弃用。
cookies 是一个 Dynamic API，其返回值无法提前知道。在布局或页面中使用它将使路由选择动态渲染。
.delete 方法只能在以下情况下调用：
- 在 Server Action 或 Route Handler 中。
- 如果它属于调用 .set 的同一域。对于通配符域，特定子域必须完全匹配。此外，代码必须在与你要删除的 cookie 相同的协议（HTTP 或 HTTPS）上执行。
HTTP 不允许在流式传输开始后设置 cookies，因此你必须在 Server Action 或 Route Handler 中使用 .set。

在 Server Components 中处理 cookies 时，重要的是要理解 cookies 从根本上来说是一种客户端存储机制：

读取 cookies 在 Server Components 中有效，因为你正在访问客户端浏览器在 HTTP 请求头中发送到服务器的 cookie 数据。
设置 cookies 不能直接在 Server Component 中完成，即使使用 Route Handler 或 Server Action 也不行。这是因为 cookies 实际上是由浏览器存储的，而不是服务器。

服务器只能发送指令（通过 Set-Cookie 头）告诉浏览器存储 cookies——实际的存储发生在客户端。这就是为什么修改状态的 cookie 操作（.set、.delete、.clear）必须在 Route Handler 或 Server Action 中执行，以便可以正确设置响应头。

在 Server Action 中设置或删除 cookie 后，Next.js 会在服务器上重新渲染当前页面及其布局，以便 UI 反映新的 cookie 值。请参阅缓存指南。

UI 不会卸载，但依赖于来自服务器的数据的副作用将重新运行。

要刷新缓存的数据，请在 action 中调用 revalidatePath 或 revalidateTag。

示例

你可以使用 (await 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

你可以使用 (await 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>Name: {cookie.name}</p>
      <p>Value: {cookie.value}</p>
    </div>
  ))
}

你可以在 Server Action 或 Route Handler 中使用 (await 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: '/',
  })
}

你可以使用 (await 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')
}

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

app/actions.ts

TypeScript

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

版本历史

版本	变更
`v15.0.0-RC`	`cookies` 现在是一个异步函数。可使用 codemod。
`v13.0.0`	引入 `cookies`。