NextJS服务端函数删除Cookie时抛出权限错误问题排查

问题核心 #

你在NextJS服务端调用后端API时，想在返回401（凭证过期）时删除iron-session的Cookie，但即使给相关文件加了'use server'标记，依然触发错误：Error: Cookies can only be modified in a Server Action or Route Handler。

原因分析 #

虽然加了'use server'，但如果修改Cookie的操作不是直接在Server Action或Route Handler的顶层上下文执行，NextJS依然会限制这个操作——比如你的deleteCookie是在通用的fetchWrapper里调用，而fetchWrapper可能被嵌套调用，导致上下文丢失，无法识别为合法的Cookie修改场景。

解决办法 #

1. 把Cookie删除逻辑移到Server Action/Route Handler中

不要在fetchWrapper里直接处理Cookie删除，而是让fetchWrapper返回响应结果，在调用它的Server Action或Route Handler里判断状态码，再执行删除操作：

// 标记为Server Action的文件
'use server';
import { cookies } from 'next/headers';
import { fetchWrapper } from './fetchWrapper';

export async function getProtectedData() {
  const response = await fetchWrapper('/api/protected-resource');
  
  if (response.status === 401) {
    // 直接在当前Server Action上下文里删除Cookie
    cookies().delete('your-session-cookie-name');
    // 这里可以额外处理重定向或错误提示
  }

  if (!response.ok) throw new Error('请求失败');
  return response.json();
}

2. 调整fetchWrapper的职责

让fetchWrapper只负责封装请求逻辑（比如带上凭证头），不处理Cookie或错误跳转，把这些逻辑交给上层的Server Action：

// fetchWrapper.ts
'use server';
import { getSession } from './session';

export async function fetchWrapper(url: string, options: RequestInit = {}) {
  const session = await getSession();
  const authHeaders = session.token ? { Authorization: `Bearer ${session.token}` } : {};

  return await fetch(`https://your-backend-api.com${url}`, {
    ...options,
    headers: { ...options.headers, ...authHeaders },
  });
}

3. 用iron-session内置方法销毁会话

既然用了iron-session，直接用它的destroy方法来删除会话Cookie，比手动调用cookies().delete更可靠，也能避免上下文问题：

'use server';
import { getSession } from './session';

export async function handleSessionExpiry() {
  const session = await getSession();
  await session.destroy(); // 自动删除对应的会话Cookie
}

4. 检查异步调用的上下文

确保所有涉及Cookie修改的代码都在'use server'标记的顶层函数中执行，不要在嵌套的匿名函数、Promise回调里操作cookies()——NextJS的Server Action上下文不会穿透这些嵌套结构。

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