NNext.js 中文网 GitHub

cookies

cookies 函数的 API 参考。

cookies 是一个异步函数,允许你在 Server Components 中读取传入 HTTP 请求的 cookie,并在 Server Functions 或 Route Handlers 中读取/写入传出请求的 cookie。

app/page.tsx
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()对象数组返回所有匹配名称的 cookie 列表。
has('name')Boolean接受一个 cookie 名称,并根据该 cookie 是否存在返回布尔值。
set(name, value, options)-接受 cookie 名称、值和选项,并设置传出请求的 cookie。
delete(name)-接受一个 cookie 名称并删除该 cookie。
toString()String返回 cookie 的字符串表示。

选项#

设置 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 的优先级
partitionedBoolean指示 cookie 是否为分区(partitioned)。

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

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

小知识#

  • cookies 是一个返回 promise 的异步函数。你必须使用 async/await 或 React 的 use 函数来访问 cookie。
    • 在 14 及更早版本中,cookies 是一个同步函数。为了向后兼容,在 Next.js 15 中你仍可以同步访问它,但此行为将来会被弃用。
  • cookies 是一个请求时 API,其返回值无法提前知晓。
  • 使用 Cache Components 时,在 <Suspense> 边界内调用 cookies() 只会在请求时流式传输该子树,而路由的其余部分会被预渲染。在边界外调用它会阻止该路由被预渲染。有关修复选项,请参阅 Next.js 在预渲染期间遇到运行时数据。
  • 不使用 Cache Components 时,在布局或页面中使用 cookies 会使该路由选择动态渲染。
  • .delete 方法只能在以下情况下调用:
    • 在 Server Function 或 Route Handler 中。
    • 如果它属于调用 .set 的同一域名。对于通配符域名,特定子域名必须完全匹配。此外,代码必须在与要删除的 cookie 相同的协议(HTTP 或 HTTPS)上执行。
  • HTTP 不允许在流式传输开始后设置 cookie,因此你必须在 Server Function 或 Route Handler 中使用 .set。

在 Server Components 中处理 cookie 时,重要的是要理解 cookie 本质上是一种客户端存储机制:

  • 读取 cookie 在 Server Components 中是可行的,因为你访问的是客户端浏览器在 HTTP 请求标头中发送给服务器的 cookie 数据。
  • 设置 cookie 在 Server Component 渲染期间不受支持。要修改 cookie,请从客户端调用 Server Function 或使用 Route Handler。

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

在 Server Function 中设置或删除 cookie 后,当该函数用作 Server Action(例如传递给表单的 action 属性)时,Next.js 可以在一次服务器往返中同时返回更新后的 UI 和新数据。请参阅缓存与重新验证。

UI 不会被卸载,但依赖于来自服务器数据的 effect 会重新运行。

要同时刷新缓存数据,请在函数内调用 revalidatePath 或 revalidateTag。

示例#

你可以使用 (await 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 '...'
}
app/page.js
import { cookies } from 'next/headers'

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

你可以使用 (await 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>
  ))
}
app/page.js
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 Function 或 Route Handler 中使用 (await 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')
  // 或
  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: '/',
  })
}

你可以使用 (await 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 '...'
}
app/page.js
import { cookies } from 'next/headers'

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

有三种删除 cookie 的方法。

使用 delete() 方法:

app/actions.ts
'use server'

import { cookies } from 'next/headers'

export async function deleteCookie(data) {
  const cookieStore = await cookies()
  cookieStore.delete('name')
}
app/actions.js
'use server'

import { cookies } from 'next/headers'

export async function deleteCookie(data) {
  const cookieStore = await cookies()
  cookieStore.delete('name')
}

设置一个同名且值为空的新 cookie:

app/actions.ts
'use server'

import { cookies } from 'next/headers'

export async function deleteCookie(data) {
  const cookieStore = await cookies()
  cookieStore.set('name', '')
}
app/actions.js
'use server'

import { cookies } from 'next/headers'

export async function deleteCookie(data) {
  const cookieStore = await cookies()
  cookieStore.set('name', '')
}

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

app/actions.ts
'use server'

import { cookies } from 'next/headers'

export async function deleteCookie(data) {
  const cookieStore = await cookies()
  cookieStore.set('name', 'value', { maxAge: 0 })
}
app/actions.js
'use server'

import { cookies } from 'next/headers'

export async function deleteCookie(data) {
  const cookieStore = await cookies()
  cookieStore.set('name', 'value', { maxAge: 0 })
}

版本历史#

版本变更
v15.0.0-RCcookies 现在是异步函数。提供有 codemod。
v13.0.0引入 cookies。
Next.js 中文网