在服务端（server/api 或 server/routes 中）调用第三方或内部 API，常用且推荐的方式有三种，按场景选用：
- 直接用 $fetch（最简单）
- 适合不需要转发当前请求头/上下文的外部请求。
- 内部相对路径时，SSR 会做“直连”（避免额外 HTTP 往返）。($fetch)
// server/api/external.get.ts
export default defineEventHandler(async () => {
return await $fetch('https://api.example.com/data')
})
- 用 event.$fetch（在服务端路由内转发上下文与头部）
- 会自动转发当前请求的上下文与安全头部（会过滤不该转发的头）。适合需要带上用户 cookie/认证头的场景。(Forwarding context & headers)
// server/api/forward.get.ts
export default defineEventHandler((event) => {
return event.$fetch('https://api.example.com/needs-auth')
})
- 自定义 $fetch 实例并注入（统一 baseURL、鉴权、错误处理）
- 通过插件创建
$api，在服务端与客户端都可用；在组件中可配合 useAsyncData/useFetch 使用。(Custom $fetch)
// plugins/api.ts
export default defineNuxtPlugin((nuxtApp) => {
const api = $fetch.create({ baseURL: 'https://api.example.com' })
return { provide: { api } }
})
// server/api/by-plugin.get.ts
export default defineEventHandler(async () => {
const { $api } = useNuxtApp()
return await $api('/items')
})
补充要点
- 在组件里如果要 SSR 安全并避免二次请求，用 useFetch/useAsyncData 包裹；它们会在服务端自动转发必要头部（相对 URL 时）。(Data Fetching 概览, useRequestFetch/转发说明, 传递客户端头部)
- 仅用
$fetch时，SSR 不会自动带上用户头部；如需转发，请在服务端用event.$fetch，或在组件端改用 useFetch/useRequestFetch。(Passing headers with $fetch)
