如何为Nuxt3插件中自定义ofetch实例的返回值正确添加类型？

问题分析 #

你在Nuxt3插件中创建的自定义ofetch实例通过provide暴露后，Nuxt的类型系统无法自动识别$api.raw()返回的具体响应类型，导致推断为FetchResponse<?>，进而访问response._data.type时出现类型错误。直接使用<any>虽然能消除警告，但违背了类型安全的原则。

解决方案 #

1. 给自定义ofetch实例指定泛型类型

在创建ofetch实例时，明确指定响应数据的类型，让类型系统提前知晓返回值结构：

import type { FetchInstance, FetchResponse } from 'ofetch';

// 根据业务需求定义响应类型，比如下载场景用ArrayBuffer
type CustomApiResponse<T = ArrayBuffer> = FetchResponse<T>;

const api = $fetch.create<CustomApiResponse>({
  // 你的默认配置，比如baseURL、headers等
});

export default defineNuxtPlugin(() => {
  return {
    provide: {
      api
    }
  };
});

2. 扩展Nuxt的全局类型声明

为了让$api在整个项目中都能获得正确的类型提示，需要在项目的类型声明文件中扩展Nuxt的App类型：

在项目根目录的types文件夹下创建nuxt.d.ts（无则新建），添加以下内容：

import type { FetchInstance } from 'ofetch';

declare module '#app' {
  interface NuxtApp {
    // 可根据需求定义更通用的泛型，比如FetchInstance<any>支持多种类型
    $api: FetchInstance<ArrayBuffer>;
  }
}

declare module '@nuxt/schema' {
  interface AppConfig {
    api?: FetchInstance<ArrayBuffer>;
  }
}

export {};

3. 调用raw方法时显式指定类型（推荐）

如果接口需要支持多种响应类型（比如有时返回JSON，有时返回ArrayBuffer），可以在调用raw时显式指定具体类型，这比用<any>更安全且清晰：

const downloadFile = async (url: string, method: 'GET' | 'POST', params: any | null, filename?: string) => {
  const options = params
    ? ({ method, body: JSON.stringify(params), responseType: 'arrayBuffer' } as const)
    : ({ method, responseType: 'arrayBuffer' } as const);
  // 显式指定响应数据类型为ArrayBuffer
  const response = await $api.raw<ArrayBuffer>(url, options);
  const type = response._data.type ?? response.headers?.get('content-type');
};

说明 #

以上方法通过明确类型声明，让Nuxt的类型系统能正确推断$api的返回值类型，既解决了类型错误，又保持了类型安全，避免了<any>带来的类型模糊问题。

内容的提问来源于stack exchange，提问作者Tim