v3.16
Nuxt on GitHub

在 Nuxt 中自定义 useFetch

如何在 Nuxt 中为调用外部 API 创建自定义 fetcher。

在 Nuxt 中开发时，你可能需要制作前端并调用外部 API，并且你可能希望为从你的 API 获取数据设置一些默认选项。

$fetch 工具函数（由 useFetch 组合式函数使用）故意设计为不可全局配置。这是为了确保整个应用中的获取行为保持一致，并且其他集成（如模块）可以依赖核心工具（如 $fetch）的行为。

然而，Nuxt 提供了一种方式，让你可以为你的 API（或多个 API，如果需要调用多个）创建自定义 fetcher。

自定义 $fetch

让我们通过一个 Nuxt 插件 创建一个自定义 $fetch 实例。

$fetch 是 ofetch 的一个配置实例，支持添加 Nuxt 服务器的基础 URL，并支持在 SSR 期间直接调用函数（避免 HTTP 往返）。

假设：

plugins/api.ts
export default defineNuxtPlugin((nuxtApp) => {
  const { session } = useUserSession()

  const api = $fetch.create({
    baseURL: 'https://api.nuxt.com',
    onRequest({ request, options, error }) {
      if (session.value?.token) {
        // 注意：这依赖于 ofetch >= 1.4.0 - 你可能需要刷新你的 lockfile
        options.headers.set('Authorization', `Bearer ${session.value?.token}`)
      }
    },
    async onResponseError({ response }) {
      if (response.status === 401) {
        await nuxtApp.runWithContext(() => navigateTo('/login'))
      }
    }
  })

  // 通过 useNuxtApp().$api 暴露
  return {
    provide: {
      api
    }
  }
})

通过这个 Nuxt 插件，$api 从 useNuxtApp() 暴露出来，可以在 Vue 组件中直接进行 API 调用：

app.vue
<script setup>
const { $api } = useNuxtApp()
const { data: modules } = await useAsyncData('modules', () => $api('/modules'))
</script>
使用 useAsyncData 包装 避免在服务器端渲染时重复获取数据（服务器端和客户端在 hydration 时）。

自定义 useFetch/useAsyncData

现在 $api 已包含我们所需的逻辑，让我们创建一个 useAPI 组合式函数来替换 useAsyncData + $api 的使用：

composables/useAPI.ts
import type { UseFetchOptions } from 'nuxt/app'

export function useAPI<T>(
  url: string | (() => string),
  options?: UseFetchOptions<T>,
) {
  return useFetch(url, {
    ...options,
    $fetch: useNuxtApp().$api as typeof $fetch
  })
}

让我们使用新的组合式函数，得到一个简洁的组件：

app.vue
<script setup>
const { data: modules } = await useAPI('/modules')
</script>

如果你想自定义返回的错误类型，也可以这样做：

import type { FetchError } from 'ofetch'
import type { UseFetchOptions } from 'nuxt/app'

interface CustomError {
  message: string
  statusCode: number
}

export function useAPI<T>(
  url: string | (() => string),
  options?: UseFetchOptions<T>,
) {
  return useFetch<T, FetchError<CustomError>>(url, {
    ...options,
    $fetch: useNuxtApp().$api
  })
}
此示例展示了如何使用自定义 useFetch，但自定义 useAsyncData 的结构是相同的。
阅读并编辑实时示例中的内容 Docs > Examples > Advanced > Use Custom Fetch Composable.

我们目前正在讨论如何以更简洁的方式创建自定义 fetcher，参见 https://github.com/nuxt/nuxt/issues/14736。