如何在Nuxt 3的API与中间件中服务端使用Cookie？

一、API中正确设置Cookie #

要在服务端API中设置Cookie，必须使用setCookie函数并传入event对象，同时配置必要的Cookie属性确保跨路径可访问：

// ~/server/api/auth.post.ts
export default defineEventHandler(async (event) => {
  // 生成认证令牌（示例逻辑）
  const authToken = 'your-generated-jwt-token';

  // 设置Cookie，核心是传入event并配置关键属性
  setCookie(event, 'auth_token', authToken, {
    httpOnly: true, // 禁止前端JS读取，提升安全性
    secure: process.env.NODE_ENV === 'production', // 生产环境强制HTTPS传输
    sameSite: 'strict',
    path: '/', // 确保全站所有路径都能访问该Cookie
    maxAge: 60 * 60 * 24 * 7 // 有效期设为7天
  });

  return { success: true, message: '登录成功' };
});

你之前设置失败大概率是两个原因：一是未将event传入setCookie函数，二是没配置path: '/'导致Cookie仅在/api路径下生效。

二、中间件中读取Cookie的正确方式 #

Nuxt 3的路由中间件读取Cookie分两种场景，若使用httpOnly类型的Cookie，必须确保中间件在服务端运行：

方式1：创建服务端专属中间件 #

将中间件文件名改为logged.server.ts，这样它只会在服务端执行，天然能读取到请求头中的Cookie：

// ~/middleware/logged.server.ts
export default defineNuxtRouteMiddleware((to, from) => {
  // 服务端运行时，useCookie会自动从请求头获取Cookie
  const authToken = useCookie('auth_token');

  // 无有效令牌则重定向到登录页
  if (!authToken.value) {
    return navigateTo('/login');
  }

  // 可选：验证令牌有效性（可调用服务端API做校验）
  // const isValid = await $fetch('/api/verify-token', {
  //   method: 'POST',
  //   body: { token: authToken.value }
  // });
  // if (!isValid) return navigateTo('/login');
});

方式2：在普通中间件中强制服务端逻辑 #

若不想修改文件名，可通过useRequestHeaders手动解析Cookie（仅服务端生效）：

// ~/middleware/logged.ts
import { parseCookies } from 'h3'

export default defineNuxtRouteMiddleware((to, from) => {
  // 仅在服务端执行Cookie读取逻辑
  if (process.server) {
    const headers = useRequestHeaders(['cookie']);
    const cookies = parseCookies(headers);
    const authToken = cookies.auth_token;

    if (!authToken) {
      return navigateTo('/login');
    }
  }
});

三、其他简易认证方案建议 #

• 官方Nuxt Auth模块：如果不想手动实现完整流程，@nuxt/auth模块提供了开箱即用的认证能力，支持Cookie、JWT等多种存储方式，适合快速搭建系统，但需要学习模块配置规则。
• 前端状态存储（不推荐）：若对安全性要求不高，也可将令牌存在useState中，但存在XSS攻击风险，远不如httpOnly Cookie安全。

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