理解 useFetch 与 Cookie 传递的基础
为什么 Cookies 会影响请求头
在前端与后端的通信中，Cookie 是客户端与服务器之间的认证与会话凭证，它通过请求头中的 Cookie 字段进行传递。使用 Nuxt 3 的 useFetch 时，请求头的构造直接决定了下游 API 能否正确识别并保持会话状态。因此，理解浏览器对 Cookie 的处理机制，是实现正确传递的第一步。
当请求发生在同源场景下，浏览器会自动附带相关的 Cookie，因为同源策略允许在同一源下共享 cookie。若涉及跨源请求，浏览器不会默认带上 cookie，除非你明确设置 credentials 选项为 include 或 same-origin。这一步是跨域 Cookie 传递的关键，需要在 useFetch 的请求选项中进行配置。
在服务端渲染（SSR）的场景中，Nuxt 3 的 useFetch 既可以在服务端执行，也可以在客户端执行。此时对 Cookie 的处理也会有所差异：服务端需要从进入请求中读取 Cookie，然后在对下游 API 的请求中传递，而客户端则依赖浏览器对 Cookie 的自动管理，除非是跨域请求需要额外配置。
服务端场景：将客户端 Cookie 传递给后端 API
使用 useRequestHeaders 获取请求头并转发
在服务端执行 useFetch 时，可以通过 useRequestHeaders 来获取来自客户端的请求头。将其中的 Cookie 字段传递给后端 API，就可以实现在服务端对用户身份的保持和会话跟踪。
通过 useRequestHeaders 可以按需选择需要转发的头部字段，例如只取 cookie，避免暴露多余头部信息。下面的示例展示了如何在一个服务端场景中，将客户端请求的 Cookie 转发给目标 API。
// 在一个服务端的页面或服务中使用
import { useRequestHeaders, useFetch } from '#app'// 仅获取来自客户端的 cookie 头
const headers = useRequestHeaders(['cookie']);// 将客户端 cookie 传递到下游 API
const { data, error } = await useFetch('https://api.example.com/profile', {headers
});// 注意：下游 API 端需要允许来自 Nuxt 3 服务端的跨域请求
在这段代码中，useRequestHeaders(['cookie']) 会捕获进入请求中的 Cookie 字段，然后以同样的字段传递给 useFetch 的 header 参数。确保下游 API 支持 CORS 并允许从你的域名发出的凭据，否则请求会被浏览器拦截或返回无效的身份信息。
客户端场景：在浏览器中通过 useFetch 传递 Cookies
设置 credentials 与跨域 Cookies
当 useFetch 运行在浏览器端，且你需要跨域请求并让浏览器附带 Cookie 时，要显式开启 credentials，使用包含 credentials: 'include' 的请求配置。这样，浏览器会在跨域请求中携带同源的 Cookie，从而实现身份验证和会话维持。
此外，某些 Cookie 是 HttpOnly 的，JavaScript 无法直接读取，只能由浏览器自动管理。此时你无需也不能手动写入 Cookie 字段，只需确保下游 API 能通过返回的 Set-Cookie 正确设置浏览器端 Cookie，且前后端域名匹配或 CORS 设置正确。
以下示例展示了在浏览器端使用 useFetch 进行跨域请求并让 Cookie 自动带上。注意在跨域场景中添加 credentials，以及在服务器端做好 CORS 配置。
// 页面中在客户端发起跨域请求
import { useFetch } from '#app'const { data, error } = await useFetch('https://api.example.com/public/profile', {// 启用跨域携带 cookiecredentials: 'include'
});// 如果 API 响应设置了 Set-Cookie，浏览器会在后续请求中继续携带 cookies
在这段代码中，credentials: 'include' 让浏览器在跨域请求中携带 Cookie；如果目标 API 与当前页面同源，浏览器也会正常附带 Cookie。请确保目标服务端正确配置 CORS 与允许凭据，否则浏览器会拒绝带 cookie 的请求。
完整实战案例：端到端实现
项目结构与关键代码
在一个真实的 Nuxt 3 项目中，端到端实现通常包含以下要点：服务端在初始请求中读取客户端 Cookie，将 Cookie 转发到下游 API，以及在客户端场景下确保跨域请求时的凭据处理。下面给出一个简化的端到端示例，以帮助你快速落地。
第一步，创建一个服务端页面，用于在 SSR 场景中转发 Cookie 给下游 API。下面的代码演示了如何在页面的脚本部分使用 useRequestHeaders 获取 cookie，并通过 useFetch 发送请求。
// pages/profile.server.ts (服务端页面示例)
import { defineEventHandler, getQuery, useRequestHeaders, useFetch } from '#app'// 服务端处理：转发客户端 cookie
export default defineEventHandler(async (event) => {const hdrs = useRequestHeaders(['cookie'])const { data, pending, error } = await useFetch('https://api.example.com/profile', {headers: hdrs})// 将下游结果返回给客户端return data.value
})
第二步，在客户端页面中，通过 useFetch 呼叫一个 API 代理，将 cookies 以浏览器的方式管理。此处演示带上 credentials，确保跨域场景中的 cookie 传递。
// pages/profile.client.ts (客户端页面示例)
import { useFetch } from '#app'const { data, error } = await useFetch('/api/profile-proxy', {credentials: 'include'
})// 页面中可直接渲染 data，若需要，可以在 标签内绑定 data.value 等
第三步，代理层需要一个 API 路由来接收客户端请求并将其转发到实际后端。下面是一个简单的代理路由实现：
// server/api/profile-proxy.ts
import { defineEventHandler, useBody, useQuery } from '#app'
import fetch from 'node-fetch' // 服务器端请求库，或内置 fetchexport default defineEventHandler(async (event) => {// 将客户端请求的 cookie 通过头部传递给下游 APIconst cookies = event.req.headers.cookie ?? ''const downstreamRes = await fetch('https://api.example.com/profile', {headers: {'Cookie': cookies},method: 'GET'})const json = await downstreamRes.json()return json
})
第四步，综合起来，你可以在页面中实现端到端的数据获取：先通过服务端获取客户端 Cookie，并转发到下游 API；然后在客户端通过代理路由继续交互，确保会话的一致性与安全性。>通过综合使用 useRequestHeaders、useFetch 与代理 API，可以实现对客户端 Cookie 的正确传递与使用。
注意事项与排错
HttpOnly Cookies 与文档可访问性
如果后端设置了 HttpOnly 的 Cookie，那么前端的 JavaScript 将无法读取该 Cookie，只有浏览器会在同源请求中自动携带它们。不要尝试手动写入 HttpOnly Cookie，应通过服务器设置响应头中的 Set-Cookie 来管理。对于客户端需要传递的自定义 Cookie，可以使用 document.cookie 读取可访问的 Cookie，并在必要时通过合规的请求头传递，但 HttpOnly Cookie 仍需由浏览器自行维护。
在服务端转发 Cookie 时，确保请求头中只包含需要的字段，避免泄露敏感头部信息，尤其是在多租户或跨域场景中。通过 useRequestHeaders 的参数列表来精确筛选要转发的头部，是一个良好的做法。
另外，排错时可以检查以下常见问题：浏览器控制台的 CORS 错误、未包含 cookie 的跨域请求以及 代理请求的响应头是否带有 Set-Cookie 等。确保服务器端的响应头中对 Access-Control-Allow-Credentials、Access-Control-Allow-Origin 等字段进行正确配置。
本篇文章围绕“Nuxt 3 useFetch 时如何正确传递客户端 Cookie 请求头？”展开，提供了从基础概念到服务端转发、客户端跨域带 cookie、以及完整实战案例的完整路径。通过正确使用 useRequestHeaders、useFetch 以及在必要场景下的代理路由，可以实现对客户端 Cookie 的准确传递与安全处理，确保你的应用在多场景下都能保持稳定的会话与认证能力。
