在服务端(server/api 或 server/routes 中)调用第三方或内部 API,常用且推荐的方式有三种,按场景选用:
- 直接用 $fetch(最简单)
- 适合不需要转发当前请求头/上下文的外部请求。
- 内部相对路径时,SSR 会做"直连"(避免额外 HTTP 往返)。($fetch)
dart
// server/api/external.get.ts
export default defineEventHandler(async () => {
return await $fetch('https://api.example.com/data')
})
- 用 event.$fetch(在服务端路由内转发上下文与头部)
- 会自动转发当前请求的上下文与安全头部(会过滤不该转发的头)。适合需要带上用户 cookie/认证头的场景。(Forwarding context & headers)
csharp
// 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)
javascript
// 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)