Cookie

cookies 是一个异步函数，允许您在 Server Components 中读取 HTTP 入站请求的 cookies，并在 Server Actions 或 Route Handlers 中读取/写入出站请求的 cookies。

tsx

import { cookies } from "next/headers";

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

javascript

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, default: `'/'`	将 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 是一个动态 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：

tsx

import { cookies } from "next/headers";

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

jsx

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。

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>名称: {cookie.name}</p>
            <p>值: {cookie.value}</p>
        </div>
    ));
}

jsx

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

您可以在 Server Action 或 Route Handler 中使用 (await cookies()).set(name, value, options) 方法来设置 cookie。options 对象是可选的。

tsx

"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: "/",
    });
}

javascript

"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: "/",
    });
}

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

tsx

import { cookies } from "next/headers";

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

jsx

import { cookies } from "next/headers";

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

删除 cookies

有三种方法可以删除 cookie。

使用 delete() 方法：

tsx

"use server";

import { cookies } from "next/headers";

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

javascript

"use server";

import { cookies } from "next/headers";

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

设置一个同名但值为空的新 cookie：

tsx

"use server";

import { cookies } from "next/headers";

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

javascript

"use server";

import { cookies } from "next/headers";

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

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

tsx

"use server";

import { cookies } from "next/headers";

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

javascript

"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-RC`	`cookies` 现在是一个异步函数。提供了 codemod。
`v13.0.0`	引入 `cookies`。

文档导航

参考

方法

选项

须知

理解 Server Components 中的 Cookie 行为

理解 Server Actions 中的 Cookie 行为

示例

获取单个 cookie

获取所有 cookies

设置 cookie

检查 cookie 是否存在

删除 cookies

版本历史

参考

方法

选项

须知

理解 Server Components 中的 Cookie 行为

理解 Server Actions 中的 Cookie 行为

示例

获取单个 cookie

获取所有 cookies

设置 cookie

检查 cookie 是否存在

删除 cookies

版本历史