Next.js 15路由处理器中使用Cookies API无法操作Cookie求助

问题根源 #

你遇到的核心问题有两个：

1. 服务端组件的fetch上下文错误：服务端组件内的fetch是在服务器环境执行的，请求携带的是服务器自身的Cookie上下文，而非用户浏览器的Cookie。因此调用/api/logout后，删除的只是服务器临时生成的CookieStore，完全不会影响用户浏览器中的Cookie。
2. Route Handler中不必要的await：Next.js 13+（包括15）的Route Handler里，cookies()是同步函数，不需要用await包裹，多余的await可能导致CookieStore获取异常。

解决方案 #

方案1：改用客户端组件发起注销请求 #

将页面改为客户端组件，让fetch在浏览器环境执行，这样请求会自动携带用户浏览器的Cookie，Route Handler的删除操作才能生效。

客户端页面代码：

// app/upload-documents/page.tsx
'use client';

import { useEffect } from 'react';
import PageContainer from './PageContainer';

const UploadDocumentsPage = () => {
  useEffect(() => {
    const performLogout = async () => {
      // 浏览器端发起请求，自动携带当前域名的Cookie
      await fetch('/api/logout', { 
        method: 'POST', 
        credentials: 'same-origin' // 显式指定携带同源Cookie，可省略（默认同源携带）
      });
      // 可在此添加注销后的逻辑，比如跳转到登录页
      // window.location.href = '/login';
    };

    performLogout();
  }, []);

  return <PageContainer>Content UploadDocumentsPage</PageContainer>;
};

export default UploadDocumentsPage;

修正后的Route Handler：

// app/api/logout/route.ts
import { NextResponse } from 'next/server';
import { cookies } from 'next/headers';

export async function POST() {
  const cookieStore = cookies(); // 同步获取，无需await
  // 必须匹配原Cookie的属性（比如path），否则删除无效
  cookieStore.delete('token', { path: '/' });

  return NextResponse.json({ status: 'success' });
}

方案2：使用Server Actions直接处理（推荐） #

Next.js的Server Actions允许在服务端组件中直接调用服务端逻辑，且会关联用户请求上下文，无需额外的API路由，更简洁高效。

定义Server Action：

// app/actions.ts
'use server';

import { cookies } from 'next/headers';

export async function logoutAction() {
  const cookieStore = cookies();
  // 匹配原Cookie的path等属性
  cookieStore.delete('token', { path: '/' });
}

在服务端组件中调用：

// app/upload-documents/page.tsx
import { logoutAction } from '@/app/actions';
import PageContainer from './PageContainer';

const UploadDocumentsPage = async () => {
  // 直接调用Server Action，自动关联用户请求上下文
  await logoutAction();

  return <PageContainer>Content UploadDocumentsPage</PageContainer>;
};

export default UploadDocumentsPage;

关键注意事项 #

• 删除Cookie时，必须严格匹配原Cookie的所有属性（path、domain、secure等）。例如原Cookie的path是/dashboard，删除时如果只写cookieStore.delete('token')会无效，必须指定{ path: '/dashboard' }。
• 若Cookie设置了secure: true，则只能在HTTPS环境下操作，本地开发需开启HTTPS（Next.js可通过next dev --experimental-https启动）。

内容的提问来源于stack exchange，提问作者Nawin Poolsawad