跳到主要内容
Nuxt 中文
开始使用

useFetch

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

该组合式函数提供了对 useAsyncData 和 $fetch 的便捷封装。它会自动为请求生成 key，基于服务端路由提供请求 url 的类型提示，并推断 API 响应类型。

useFetch 是一个组合式函数，意在 setup 函数、插件或路由中间件中直接调用。它返回可响应的组合式值，并处理将响应添加到 Nuxt payload 中，这样它们就可以从服务端传递到客户端，在页面 hydration 时无需在客户端重新获取数据。 :

用法

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

需要一个带有预定义默认值（如 baseURL 或鉴权请求头）的自定义 useFetch？使用 createUseFetch 创建一个完全类型化的自定义组合式函数。 :

你无需 await useFetch。在服务端，无论哪种情况 Nuxt 都会等待 promise 解析完成后再渲染，因此返回的 HTML 始终包含数据。await 影响的是调用之后发生的事情：使用它时，执行会暂停直到 data 被填充，且客户端导航会阻塞直到数据就绪；不使用它时，执行立即继续，data 在请求解析完成前保持其默认值，在客户端导航时你需要使用返回的 status 和 error ref 自行处理加载和错误状态。这与 lazy 选项效果类似，不过 lazy 是显式选择非阻塞导航的方式。 :

data、status 和 error 是 Vue ref，在 <script setup> 中通过 .value 访问它们的值，而 refresh/execute 和 clear 是普通函数。 :

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

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

上面的示例会生成 https://api.nuxt.com/modules?param1=value1&param2=value2。

你也可以使用 拦截器：

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

响应式 Key 与共享状态

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

app/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>

自动生成的 key 对每个调用位置是唯一的，因此在不同组件中以相同的 URL 和选项调用 useFetch 不会共享状态，每次调用都会执行自己的请求。同一个组件的多个实例会共享状态，因为它们使用相同的调用位置。要在不同组件间共享相同的 data、error 和 status ref，请为每个调用提供相同的显式 key：

app/components/ComponentA.vue
<script setup lang="ts">
// 与 ComponentB 共享数据——只发出一个请求
const { data } = await useFetch('/api/random', { key: 'random' })
</script>
app/components/ComponentB.vue
<script setup lang="ts">
// 与 ComponentA 共享数据——只发出一个请求
const { data } = await useFetch('/api/random', { key: 'random' })
</script>

:

使用 useFetch 创建的 keyed 状态可以通过 useNuxtData 在你的 Nuxt 应用中获取。 :

useFetch 是编译器转换的保留函数名，因此你不应该把自己的函数命名为 useFetch。要创建带有预定义选项的自定义变体，请改用 createUseFetch。 :

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

阅读更多

响应式 Fetch 选项

fetch 选项可以作为响应式提供，支持 computed、ref 和 computed getters。当响应式 fetch 选项更新时，它会使用更新后的解析值触发重新获取。

app/pages/index.vue
const searchQuery = ref('initial')
const { data } = await useFetch('/api/search', {
  query: { q: searchQuery },
})
// 触发重新获取：/api/search?q=new%20search
searchQuery.value = 'new search'

如果需要，你可以使用 watch: false 关闭此行为：

app/pages/index.vue
const searchQuery = ref('initial')
const { data } = await useFetch('/api/search', {
  query: { q: searchQuery },
  watch: false,
})
// 不会触发重新获取
searchQuery.value = 'new search'

类型

Signature
export function useFetch<ResT, ErrorT = NuxtError<unknown>, DataT = ResT> (
  url: string | Request | Ref<string | Request> | (() => string | Request),
  options?: UseFetchOptions<ResT, DataT>,
): AsyncData<DataT, ErrorT> & Promise<AsyncData<DataT, ErrorT>>

type UseFetchOptions<ResT, DataT = ResT> = {
  key?: MaybeRefOrGetter<string>
  method?: MaybeRefOrGetter<string>
  query?: MaybeRefOrGetter<SearchParams>
  params?: MaybeRefOrGetter<SearchParams>
  body?: MaybeRefOrGetter<RequestInit['body'] | Record<string, any>>
  headers?: MaybeRefOrGetter<Record<string, string> | [key: string, value: string][] | Headers>
  baseURL?: MaybeRefOrGetter<string>
  cache?: false | 'default' | 'force-cache' | 'no-cache' | 'no-store' | 'only-if-cached' | 'reload'
  server?: boolean
  lazy?: boolean
  immediate?: boolean
  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
  deep?: boolean
  dedupe?: 'cancel' | 'defer'
  timeout?: number
  enabled?: MaybeRefOrGetter<boolean>
  default?: () => DataT | Ref<DataT>
  transform?: (input: ResT) => 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>
  pending: Ref<boolean>
  refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>
  execute: (opts?: AsyncDataExecuteOptions) => Promise<void>
  clear: () => void
  error: Ref<ErrorT | undefined>
  status: Ref<AsyncDataRequestStatus>
}

interface AsyncDataExecuteOptions {
  dedupe?: 'cancel' | 'defer'
  timeout?: number
  signal?: AbortSignal
}

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

参数

  • URL (string | Request | Ref<string | Request> | () => string | Request)：要获取的 URL 或请求。可以是字符串、Request 对象、Vue ref，或返回字符串/Request 的函数。支持动态端点的响应式。
  • options（对象）：fetch 请求的配置。继承自 unjs/ofetch 选项和 AsyncDataOptions。所有选项可以是静态值、ref 或计算值。
选项类型默认值描述
keyMaybeRefOrGetter<string>自动生成用于去重的唯一 key。如果未提供，则从 URL、选项和源代码中的调用位置生成。
methodMaybeRefOrGetter<string>'GET'HTTP 请求方法。
queryMaybeRefOrGetter<SearchParams>-要附加到 URL 的查询/搜索参数。别名：params。
paramsMaybeRefOrGetter<SearchParams>-query 的别名。
bodyMaybeRefOrGetter<RequestInit['body'] | Record<string, any>>-请求体。对象会自动字符串化。
headersMaybeRefOrGetter<Record<string, string> | [key, value][] | Headers>-请求头。
baseURLMaybeRefOrGetter<string>-请求的基础 URL。
cachefalse | string-缓存控制。布尔值禁用缓存，或使用 Fetch API 的值：default、no-store 等。
serverbooleantrue是否在服务端获取。
lazybooleanfalse如果为 true，则在路由加载后解析（不阻塞导航）。
immediatebooleantrue如果为 false，则阻止请求立即发起。
default() => DataT-在 async 解析之前 data 默认值的工厂函数。
timeout v4.2number-在请求超时前等待的毫秒数（默认 undefined，表示不超时）
transform(input: DataT) => DataT | Promise<DataT>-解析后转换结果的函数。
getCachedData v3.8(key, nuxtApp, ctx) => DataT | undefined-返回缓存数据的函数。默认实现见下文。
pickstring[]-仅从结果中挑选指定的 key。
watchMultiWatchSources | false-要监视并自动刷新的响应式源数组。false 禁用监视。
deep v3.8booleanfalse以深层 ref 对象形式返回数据。默认为 false 以获得更好性能（浅层 ref 对象）。
dedupe v3.9'cancel' | 'defer''cancel'避免同时对同一 key 多次获取。
enabled v4.5booleantrue控制请求是否可以运行的屏障。为 false 时，每次执行都会被阻塞（初始获取、execute/refresh 和 watch 触发），且从 true → false 切换会取消任何进行中的请求而不清除 data。重新启用不会自行重新获取。
$fetch v3.2typeof globalThis.$fetch-自定义 $fetch 实现。参见 Nuxt 中的自定义 useFetch

所有 fetch 选项都可以给定 computed 或 ref 值。这些会被监视，并在更新时使用任何新值自动发起新请求（除非 watch 设为 false）。 :

getCachedData 默认值：

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

这仅在 nuxt.config 中启用了 experimental.payloadExtraction 时才会缓存数据。

返回值

该组合式函数返回一个可以 await 的 Promise，这使得可以在 <script setup> 中直接使用 data（即会有一个值存在，而不是 undefined）。你也可以在不 await 返回值的情况下直接解构这些值，这种情况下直到获取完成之前 data 在 <script setup> 中可能仍为 undefined。

即使你不 await 返回值，在 SSR 期间 Nuxt 也会等待请求完成并将解析后的数据发送到客户端。 :

如果你没有在服务端获取数据（例如使用 server: false），那么数据在 hydration 完成之前不会被获取。这意味着即使在客户端 await useFetch，data 在 <script setup> 中也会保持 undefined。 :

名称类型描述
dataRef<DataT | undefined>异步 fetch 的结果。
refresh(opts?: AsyncDataExecuteOptions) => Promise<void>手动刷新数据的函数。默认情况下，Nuxt 会等待一次 refresh 完成之后才能再次执行。
execute(opts?: AsyncDataExecuteOptions) => Promise<void>refresh 的别名。
errorRef<ErrorT | undefined>如果数据获取失败的错误对象。
statusRef<'idle' | 'pending' | 'success' | 'error'>数据请求的状态。用它来区分 idle、pending、success 和 error。
pendingRef<boolean>请求进行中为 true。配合 experimental.pendingWhenIdle，当 status 为 idle 且没有可用缓存数据时也为 true。
clear() => void将 data 重置为 undefined（或提供了 options.default() 时为其值），error 重置为 undefined，将 status 设为 idle，并取消任何挂起的请求。

如果你没有 await 返回值，来自 Promise 的函数（then、catch 和 finally）可以被安全解构。 :

状态值

  • idle：请求尚未开始（例如 { immediate: false } 或服务端渲染时的 { server: false }）
  • pending：请求进行中
  • success：请求成功完成
  • error：请求失败

示例

查看示例查看示例