nuxtjs 项目中请求后端接口数据 $fetch 或 useFetch/useAsyncData 组合函数 使用场景和区别

在 Nuxt.js（特别是 Nuxt 3）项目中，$fetch、useFetch 和 useAsyncData 是三种核心的数据获取方式。它们都基于 Nitro 引擎和 Vue 3 的组合式 API，但使用场景、功能封装和适用上下文有明显区别。

下面从 功能定位、使用场景、SSR 支持、返回值、错误处理、缓存机制 等维度详细对比，并给出清晰的选型建议。

📊 一、三者对比总览

🔍 二、详细说明与使用场景

1. $fetch：底层 HTTP 客户端（灵活但无状态管理）

• 用途：发起任意 HTTP 请求（GET/POST/PUT/DELETE），类似 fetch，但更智能。
• 特点：
  • 自动解析 JSON
  • 支持 TypeScript 类型推断
  • 可在服务端或客户端运行
  • 不提供 pending/error** 状态**，需自行处理

✅ 适用场景：

• 表单提交（POST）
• 用户交互触发的请求（如点赞、删除）
• 在 server/ 端点内部调用第三方 API
• 不需要自动 SSR 预加载的动态请求

示例：

// 在组件中（客户端交互）
const submitForm = async () => {
try {
const res = await $fetch('/api/create', {
method: 'POST',
body: { name: 'John' }
})
console.log(res)
} catch (error) {
console.error('提交失败', error)
}
}

💡 在 server/api/xxx.ts 中也常用 $fetch 调用真实后端。

2. useFetch(url, options?)：专为远程数据获取设计

• 本质：useAsyncData(url, () => $fetch(url, options)) 的简写
• 自动按 URL 作为缓存 key
• 自动在 SSR 阶段执行（如果在 setup() 中调用）

✅ 适用场景：

• 页面初始化时加载列表、详情等 GET 数据
• 调用 /api/xxx 或外部 REST API（公开数据）
• 希望自动获得 data/pending/error 状态

示例：

<script setup>
// 自动 SSR + 客户端 hydration
const { data: posts, pending, error } = await useFetch('/api/posts')

// 带参数
const { data: user } = await useFetch(`/api/users/${userId}`)
</script>

<template>
<div v-if="pending">加载中…</div>
<div v-else-if="error">出错了：{{ error.message }}</div>
<div v-else>
<h1>{{ posts?.length }} 篇文章</h1>
</div>
</template>

✅ 推荐用于 页面级数据预取

3. useAsyncData(key, handler, options?)：最通用的异步数据加载器

• 用途：执行任意异步函数（不限于 HTTP 请求）
• **必须提供唯一 **key（用于缓存和去重）
• handler 函数可以是 $fetch、数据库查询、复杂计算等

✅ 适用场景：

• 需要自定义异步逻辑（如合并多个 API）
• 使用 GraphQL、WebSocket 初始化
• 调用本地 Composable 或服务层方法
• 需要精确控制缓存 key

示例：

// 合并两个 API
const { data: combinedData } = await useAsyncData('user-posts', async () => {
const [user, posts] = await Promise.all([
$fetch('/api/user'),
$fetch('/api/posts')
])
return { user, posts }
})

// 调用 composables
const { data: profile } = await useAsyncData('profile', () => fetchUserProfile())

💡 当你需要 **超越简单 **$fetch 的逻辑时，用 useAsyncData

🧠 三、如何选择？—— 决策树

需要加载页面初始数据？
├─ 是 → 数据来自一个 URL（GET）？
│ ├─ 是 → 用 useFetch(url)
│ └─ 否 → 用 useAsyncData(key, handler)
└─ 否（用户交互、提交表单等）
└─ 用 $fetch()

⚠️ 四、注意事项

1. SSR 与客户端执行时机

• useFetch / useAsyncData 必须在 setup() 顶层 await 才能触发 SSR。
• 如果在 onMounted 中调用，只在客户端执行（失去 SSR 优势）。

✅ 正确（SSR）：

<script setup>
const { data } = await useFetch('/api/data') // ✅ SSR
</script>

❌ 错误（仅 CSR）：

<script setup>
onMounted(async () => {
const { data } = await useFetch('/api/data') // ❌ 仅客户端
})
</script>

2. 缓存与重复请求

• 相同 key（useAsyncData）或相同 url（useFetch）在一次请求周期内不会重复执行。
• 可通过 refresh() 手动重新获取。

3. 错误处理

• error 是一个 ref 对象，需用 .value 访问（但在模板中自动 unwrap）
• 全局错误可通过 app.vue 的 onErrorCaptured 或 Nuxt 插件统一处理

✅ 五、总结建议

通过合理选择这三种方式，你可以构建出高性能、SEO 友好、用户体验佳的 Nuxt 应用。如需具体场景示例（如分页、搜索、认证请求）