useFetch

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

该组合式函数为 useAsyncData 和 $fetch 提供了便捷的封装。它能自动为请求生成键（key）、根据服务端路由为请求 URL 提供类型提示，并推断 API 响应类型。

useFetch 是一个旨在直接在 setup 函数、插件（plugin）或路由中间件（route middleware）中调用的组合式函数。它返回响应式的组合式函数，并负责将响应添加到 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 决议（resolve），因此返回的 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' },
})

上述示例最终生成的 URL 为 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 }) {
    // Set the request headers
    // note that this relies on ofetch >= 1.4.0 - you may need to refresh your lockfile
    options.headers.set('Authorization', '...')
  },
  onRequestError ({ request, options, error }) {
    // Handle the request errors
  },
  onResponse ({ request, response, options }) {
    // Process the response data
    localStorage.setItem('token', response._data.token)
  },
  onResponseError ({ request, response, options }) {
    // Handle the response errors
  },
})

响应式键与共享状态

你可以将计算属性（computed ref）或普通 ref 用作 URL，从而实现当 URL 改变时自动更新的动态数据获取

app/pages/[id].vue

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

// When the route changes and id updates, the data will be automatically refetched
const { data: post } = await useFetch(() => `/api/posts/${id.value}`)
</script>

自动生成的键对于每个调用处（call site）都是唯一的，因此在不同的组件中使用相同的 URL 和选项调用 useFetch 将不会共享状态，并且每次调用都会执行其自己的请求。同一个组件的多个实例确实会共享状态，因为它们使用相同的调用处。要在不同的组件之间共享相同的 data、error 和 status ref，请为每次调用提供相同的显式 key

<script setup lang="ts">
// shares the data with ComponentB - only one request is made
const { data } = await useFetch('/api/random', { key: 'random' })
</script>

<script setup lang="ts">
// shares the data with ComponentA - only one request is made
const { data } = await useFetch('/api/random', { key: 'random' })
</script>

使用 useFetch 创建的带键状态可以在整个 Nuxt 应用中通过 useNuxtData 进行检索。

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

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

在文档 > 4 X > 入门 > 数据获取中阅读更多信息。

响应式 Fetch 选项

Fetch 选项可以作为响应式数据提供，支持 computed、ref 以及计算 getter（computed getters）。当响应式 fetch 选项更新时，它将使用更新后的已解析响应式值触发重新获取（refetch）。

app/pages/index.vue

const searchQuery = ref('initial')
const { data } = await useFetch('/api/search', {
  query: { q: searchQuery },
})
// triggers a refetch: /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,
})
// does not trigger a refetch
searchQuery.value = 'new search'

类型

签名

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 = {
  /** The reason for this data request */
  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 或计算值。

选项	类型	默认	描述
`key`	`MaybeRefOrGetter<string>`	自动生成	用于去重的唯一键。如果未提供，则根据源代码中的 URL、选项和调用处位置生成。
`method`	`MaybeRefOrGetter<string>`	`'GET'`	HTTP 请求方法。
`query`	`MaybeRefOrGetter<SearchParams>`	-	要追加到 URL 的查询/搜索参数。别名：`params`。
`params`	`MaybeRefOrGetter<SearchParams>`	-	`query` 的别名。
`body`	`MaybeRefOrGetter<RequestInit['body'] \| Record<string, any>>`	-	请求体。对象会自动转换为字符串。
`headers`	`MaybeRefOrGetter<Record<string, string> \| [key, value][] \| Headers>`	-	请求头。
`baseURL`	`MaybeRefOrGetter<string>`	-	请求的基础 URL。
`缓存`	`false \| string`	-	缓存控制。布尔值用于禁用缓存，或者使用 Fetch API 值：`default`、`no-store` 等。
`服务器`	`boolean`	`true`	是否在服务端进行获取。
`lazy`	`boolean`	`false`	如果为 true，则在路由加载后决议（不阻塞导航）。
`immediate`	`boolean`	`true`	如果为 false，则防止请求立即发出。
`默认`	`() => DataT`	-	异步决议前 `data` 默认值的工厂函数。
`timeout` v4.2	`number`	-	请求超时前等待的毫秒数（默认为 `undefined`，表示无超时限制）
`transform`	`(input: DataT) => DataT \| Promise<DataT>`	-	用于在决议后转换结果的函数。
`getCachedData` v3.8	`(key, nuxtApp, ctx) => DataT \| undefined`	-	用于返回缓存数据的函数。默认实现见下文。
`pick`	`string[]`	-	仅从结果中挑选指定的键。
`watch`	`MultiWatchSources \| false`	-	要监听并自动刷新的响应式源数组。`false` 会禁用监听。
`deep` v3.8	`boolean`	`false`	以深度 ref 对象形式返回数据。为了提高性能，默认为 `false`（浅 ref 对象）。
`dedupe` v3.9	`'cancel' \| 'defer'`	`'cancel'`	避免同时多次获取相同的键。
`enabled` v4.5	`boolean`	`true`	控制请求是否可以运行的关卡。当为 `false` 时，所有执行都会被阻塞（初始获取、`execute`/`refresh` 以及 watch 触发器），并且从 `true` 切换到 `false` 会取消任何正在进行（in-flight）的请求，而不会清除 `data`。重新启用不会自动重新获取。
`$fetch` v3.2	`typeof globalThis.$fetch`	-	自定义 $fetch 实现。请参见 Nuxt 中的自定义 useFetch

所有 fetch 选项都可以赋予 computed 或 ref 值。系统将对其进行监听，如果它们更新了，将自动使用任何新值发出新请求（除非将 watch 设置为 false）。

getCachedData 默认值

默认的 getCachedData 实现

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 返回值，在这种情况下，在 fetch 完成之前，data 在 <script setup> 中可能是 undefined。

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

如果你未在服务端获取数据（例如，设置了 server: false），则在水合（hydration）完成之前，数据不会被获取。这意味着即使你在客户端 await useFetch，data 在 <script setup> 中仍将保持 undefined。

名称	类型	描述
`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'>`	数据请求的状态。用它来区分 `idle`、`pending`、`success` 和 `error`。
`pending`	`Ref<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：请求失败

示例

在文档 > 4 X > 示例 > 高级 > 使用自定义 Fetch 组合式函数中阅读并编辑在线示例。

在文档 > 4 X > 示例 > 特性 > 数据获取中阅读并编辑在线示例。

这有帮助吗？

报告问题或在 GitHub 上编辑此页

useError

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

useHead

useHead 自定义 Nuxt 应用中各个页面的头部属性。