useFetch

使用 SSR 友好的可组合函数从 API 端点获取数据。

此可组合函数是围绕 useAsyncData 和 $fetch 的便捷包装器。它会根据 URL 和获取选项自动生成键，为请求 URL 提供基于服务器路由的类型提示，并推断 API 响应类型。

useFetch 是一个设计为在设置函数、插件或路由中间件中直接调用的可组合函数。它返回响应式可组合对象，并处理将响应添加到 Nuxt 负载中，以便在页面水合时无需在客户端重新获取数据即可从服务器传递到客户端。

使用方法

pages/modules.vue

<script setup lang="ts">
const { data, status, error, refresh, clear } = await useFetch('/api/modules', {
  pick: ['title']
})
</script>

如果使用自定义的 useFetch 包装器，请不要在可组合函数中对其进行 await，因为这可能导致意外行为。请参考此配方以获取有关如何创建自定义异步数据获取器的更多信息。

data、status 和 error 是 Vue ref 对象，在 <script setup> 中使用时需要通过 .value 访问，而 refresh/execute 和 clear 是普通函数。

使用 query 选项，你可以为查询添加搜索参数。此选项扩展自 unjs/ofetch，并使用 unjs/ufo 创建 URL。对象会自动被字符串化。

const param1 = ref('value1')
const { data, status, error, refresh } = await useFetch('/api/modules', {
  query: { param1, param2: 'value2' }
})

上述示例将生成 https://api.nuxt.com/modules?param1=value1¶m2=value2。

你还可以使用拦截器：

const { data, status, error, refresh, clear } = await useFetch('/api/auth/login', {
  onRequest({ request, options }) {
    // 设置请求头
    // 注意：这依赖于 ofetch >= 1.4.0，你可能需要刷新你的锁文件
    options.headers.set('Authorization', '...')
  },
  onRequestError({ request, options, error }) {
    // 处理请求错误
  },
  onResponse({ request, response, options }) {
    // 处理响应数据
    localStorage.setItem('token', response._data.token)
  },
  onResponseError({ request, response, options }) {
    // 处理响应错误
  }
})

响应式键和共享状态

你可以使用计算属性 ref 或普通 ref 作为 URL，以实现动态数据获取，并在 URL 更改时自动更新：

pages/[id].vue

<script setup lang="ts">
const route = useRoute()
const id = computed(() => route.params.id)

// 当路由更改且 id 更新时，数据将自动重新获取
const { data: post } = await useFetch(() => `/api/posts/${id.value}`)
</script>

当在多个组件中使用相同的 URL 和选项调用 useFetch 时，它们将共享相同的 data、error 和 status ref。这确保了组件之间的一致性。

使用 useFetch 创建的键控状态可以通过 useNuxtData 在你的 Nuxt 应用中检索。

useFetch 是一个由编译器转换的保留函数名称，因此你不应该将自己的函数命名为 useFetch。

如果从 useFetch 解构出的 data 变量返回字符串而不是 JSON 解析的对象，请确保你的组件没有包含类似 import { useFetch } from '@vueuse/core' 的导入语句。

阅读更多 Docs > Getting Started > Data Fetching.

类型

签名

function useFetch<DataT, ErrorT>(
  url: string | Request | Ref<string | Request> | (() => string | Request),
  options?: UseFetchOptions<DataT>
): Promise<AsyncData<DataT, ErrorT>>

type UseFetchOptions<DataT> = {
  key?: MaybeRefOrGetter<string>
  method?: string
  query?: SearchParams
  params?: SearchParams
  body?: RequestInit['body'] | Record<string, any>
  headers?: Record<string, string> | [key: string, value: string][] | Headers
  baseURL?: string
  server?: boolean
  lazy?: boolean
  immediate?: boolean
  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
  deep?: boolean
  dedupe?: 'cancel' | 'defer'
  default?: () => DataT
  transform?: (input: DataT) => DataT | Promise<DataT>
  pick?: string[]
  $fetch?: typeof globalThis.$fetch
  watch?: MultiWatchSources | false
}

type AsyncDataRequestContext = {
  /** 数据请求的原因 */
  cause: 'initial' | 'refresh:manual' | 'refresh:hook' | 'watch'
}

type AsyncData<DataT, ErrorT> = {
  data: Ref<DataT | undefined>
  refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>
  execute: (opts?: AsyncDataExecuteOptions) => Promise<void>
  clear: () => void
  error: Ref<ErrorT | undefined>
  status: Ref<AsyncDataRequestStatus>
}

interface AsyncDataExecuteOptions {
  dedupe?: 'cancel' | 'defer'
}

type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'

参数

URL (string | Request | Ref<string | Request> | () => string | Request)：要获取的 URL 或请求。可以是字符串、Request 对象、Vue ref 或返回字符串/Request 的函数。支持响应式动态端点。
options (对象)：获取请求的配置。扩展自 unjs/ofetch 选项和 AsyncDataOptions。所有选项可以是静态值、ref 或计算值。

选项	类型	默认值	描述
`key`	`MaybeRefOrGetter<string>`	自动生成	用于去重的唯一键。如果未提供，则根据 URL 和选项生成。
`method`	`string`	`'GET'`	HTTP 请求方法。
`query`	`object`	-	附加到 URL 的查询/搜索参数。别名：`params`。支持 ref/计算值。
`params`	`object`	-	`query` 的别名。
`body`	`RequestInit['body'] \| Record<string, any>`	-	请求体。对象会自动字符串化。支持 ref/计算值。
`headers`	`Record<string, string> \| [key, value][] \| Headers`	-	请求头。
`baseURL`	`string`	-	请求的基础 URL。
`timeout`	`number`	-	终止请求的超时时间（毫秒）。
`cache`	`boolean \| string`	-	缓存控制。布尔值禁用缓存，或使用 Fetch API 值：`default`、`no-store` 等。
`server`	`boolean`	`true`	是否在服务器上获取数据。
`lazy`	`boolean`	`false`	如果为 true，则在路由加载后解析（不阻塞导航）。
`immediate`	`boolean`	`true`	如果为 false，则阻止请求立即触发。
`default`	`() => DataT`	-	在异步解析前设置 `data` 默认值的工厂函数。
`transform`	`(input: DataT) => DataT \| Promise<DataT>`	-	在解析后转换结果的函数。
`getCachedData`	`(key, nuxtApp, ctx) => DataT \| undefined`	-	返回缓存数据的函数。见下文默认值。
`pick`	`string[]`	-	仅从结果中选择指定的键。
`watch`	`MultiWatchSources \| false`	-	监听并自动刷新的响应式数据源数组。`false` 禁用监听。
`deep`	`boolean`	`false`	以深层 ref 对象返回数据。
`dedupe`	`'cancel' \| 'defer'`	`'cancel'`	避免同一键同时多次获取。
`$fetch`	`typeof globalThis.$fetch`	-	自定义 $fetch 实现。

所有获取选项都可以是 computed 或 ref 值。这些值会被监听，如果更新，将自动使用新值发起新请求。

getCachedData 默认值：

const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating 
 ? nuxtApp.payload.data[key] 
 : nuxtApp.static.data[key]

仅当 nuxt.config 中的 experimental.payloadExtraction 启用时缓存数据。

返回值

名称	类型	描述
`data`	`Ref<DataT \| undefined>`	异步获取的结果。
`refresh`	`(opts?: AsyncDataExecuteOptions) => Promise<void>`	手动刷新数据的函数。默认情况下，Nuxt 会等待一个 `refresh` 完成后再再次执行。
`execute`	`(opts?: AsyncDataExecuteOptions) => Promise<void>`	`refresh` 的别名。
`error`	`Ref<ErrorT \| undefined>`	如果数据获取失败，则为错误对象。
`status`	`Ref<'idle' \| 'pending' \| 'success' \| 'error'>`	数据请求的状态。见下文可能的值。
`clear`	`() => void`	将 `data` 重置为 `undefined`（或如果提供了 `options.default()`，则为其值），将 `error` 设置为 `undefined`，将 `status` 设置为 `idle`，并取消任何待处理的请求。

状态值

idle：请求尚未万人未开始（例如，设置了 { immediate: false } 或在服务器渲染时设置了 { server: false }）
pending：请求正在进行
success：请求成功完成
error：请求失败

如果未在服务器上获取数据（例如，使用 server: false），则在水合完成前不会获取数据。这意味着即使在客户端 await useFetch，在 <script setup> 中 data 将保持 null。

示例

阅读并编辑实时示例中的内容 Docs > Examples > Advanced > Use Custom Fetch Composable.

阅读并编辑实时示例中的内容 Docs > Examples > Features > Data Fetching.

Was this helpful?

Report an issue or Edit this page on GitHub

useError

useError 可组合函数返回正在处理的全局 Nuxt 错误。

useHead

useHead 可定制 Nuxt 应用中各个页面的 head 属性。