Nuxt3 API路由中Cookie无法保存的原因排查

核心原因 #

1. 服务器端中间件的内部请求无法将Cookie传递到浏览器
   Nuxt3的全局中间件会在SSR阶段于服务器端执行，此时通过useFetch发起的/api/setCookie请求是服务器向自身发起的内部请求，setCookie设置的Cookie仅存在于该内部请求的响应上下文里，不会被发送到用户的浏览器，自然无法持久化保存。后续的/api/getCookie内部请求是独立的上下文，也拿不到之前设置的Cookie。

2. Cookie路径默认配置限制
   h3的setCookie函数默认会将Cookie的路径设为当前请求的路径（即/api/setCookie），这会导致只有访问该精确路径的请求才会携带Cookie，即使同属/api下的其他请求也可能无法读取到。

3. 客户端请求时序问题（偶发）
   若中间件在客户端执行，第一次刷新时setCookie请求的响应还未被浏览器处理完成，紧接着发起的getCookie请求可能还未携带新设置的Cookie，导致读取失败。

解决方案 #

方案1：让中间件仅在客户端执行 #

通过process.client判断执行环境，确保useFetch请求从浏览器发起，这样setCookie的响应头会被浏览器接收并保存：

import {useStore} from "~/store/useStore";

export default defineNuxtRouteMiddleware(async () => {
  if (process.client) {
    await useFetch('/api/setCookie')
    await useFetch('/api/getCookie')
  }
});

方案2：显式配置Cookie的全局路径 #

在setCookie.ts中指定path: '/'，让Cookie在整个站点范围内生效，同时可补充安全性相关配置：

import { setCookie } from "h3";

export default defineEventHandler((event) => {
  console.log('set cookie in Event Handler')
  setCookie(event, 'test_cookie', 'test_value', {
    path: '/',
    maxAge: 86400, // 有效期1天
    httpOnly: true, // 禁止前端JS读取，增强安全性
    sameSite: 'lax'
  })
  return { hello: 'world' }
})

方案3：直接在中间件中操作Cookie（推荐） #

无需通过useFetch调用API，直接在中间件中使用h3的setCookie和getCookie方法，避免多请求上下文隔离的问题：

import {useStore} from "~/store/useStore";
import { setCookie, getCookie } from "h3";

export default defineNuxtRouteMiddleware(async () => {
  const event = useRequestEvent()
  if (!event) return
  
  setCookie(event, 'test_cookie', 'test_value', { path: '/' })
  const cookie = getCookie(event, 'test_cookie')
  console.log('get cookie in middleware', cookie)
});

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