API 参考

以下是 axios 包中所有可用函数和类的列表。这些函数可在你的项目中使用和导入。所有函数和类均受我们遵循语义化版本的承诺保护，即在未发布主版本变更的情况下，这些 API 将保持稳定不变。

实例

axios 实例是你用于发起 HTTP 请求的主要对象，它是一个创建 Axios 类新实例的工厂函数。axios 实例提供了多个请求方法，详见文档的请求别名章节。

类

Axios

Axios 类是发起 HTTP 请求的核心类，是一个创建 Axios 类新实例的工厂函数。该类提供多个 HTTP 请求方法，详见文档的请求别名章节。

constructor

创建一个新的 Axios 实例，构造函数接受一个可选的配置对象作为参数。

constructor(instanceConfig?: AxiosRequestConfig);

request

处理请求调用和响应解析，是发起 HTTP 请求的核心方法。接受一个配置对象作为参数，返回一个解析为响应对象的 Promise。

request(configOrUrl: string | AxiosRequestConfig<D>, config: AxiosRequestConfig<D>): Promise<AxiosResponse<T>>;

CancelToken 已废弃，请改用 AbortController

CancelToken 类基于 tc39/proposal-cancelable-promises 提案，用于创建可取消 HTTP 请求的令牌。该类现已废弃，推荐使用 AbortController API。

从 0.22.0 版本起，CancelToken 类已废弃，将在未来版本中移除。建议改用 AbortController API。

该类主要为了向后兼容而保留导出，未来将被移除。我们强烈不建议在新项目中使用，因此不再对其 API 进行文档说明。

函数

AxiosError

AxiosError 类是 HTTP 请求失败时抛出的错误类，继承自 Error 类并添加了额外属性。

constructor

创建一个新的 AxiosError 实例，构造函数接受可选的 message、code、config、request 和 response 作为参数。

constructor(message?: string, code?: string, config?: InternalAxiosRequestConfig<D>, request?: any, response?: AxiosResponse<T, D>);

properties

AxiosError 类提供以下属性：

// 配置实例。
config?: InternalAxiosRequestConfig<D>;

// 错误代码。
code?: string;

// 请求实例。
request?: any;

// 响应实例。
response?: AxiosResponse<T, D>;

// 表示该错误是否为 AxiosError 的布尔值。
isAxiosError: boolean;

// 错误状态码。
status?: number;

// 将错误转换为 JSON 对象的辅助方法。
toJSON: () => object;

// 错误原因。
cause?: Error;

AxiosHeaders

AxiosHeaders 类是用于管理 HTTP 请求头的工具类，提供添加、删除和获取请求头等操作方法。

此处仅列出主要方法，完整方法列表请参阅类型声明文件。

constructor

创建一个新的 AxiosHeaders 实例，构造函数接受一个可选的请求头对象作为参数。

constructor(headers?: RawAxiosHeaders | AxiosHeaders | string);

set

向请求头对象添加一个请求头。

set(headerName?: string, value?: AxiosHeaderValue, rewrite?: boolean | AxiosHeaderMatcher): AxiosHeaders;
set(headers?: RawAxiosHeaders | AxiosHeaders | string, rewrite?: boolean): AxiosHeaders;

get

从请求头对象获取一个请求头。

get(headerName: string, parser: RegExp): RegExpExecArray | null;
get(headerName: string, matcher?: true | AxiosHeaderParser): AxiosHeaderValue;

has

检查请求头对象中是否存在某个请求头。

has(header: string, matcher?: AxiosHeaderMatcher): boolean;

delete

从请求头对象移除一个请求头。

delete(header: string | string[], matcher?: AxiosHeaderMatcher): boolean;

clear

从请求头对象移除所有请求头。

clear(matcher?: AxiosHeaderMatcher): boolean;

normalize

规范化请求头对象。

normalize(format: boolean): AxiosHeaders;

concat

合并多个请求头对象。

concat(...targets: Array<AxiosHeaders | RawAxiosHeaders | string | undefined | null>): AxiosHeaders;

toJSON

将请求头对象转换为 JSON 对象。

toJSON(asStrings?: boolean): RawAxiosHeaders;

CanceledError 继承自 AxiosError

CanceledError 类是 HTTP 请求被取消时抛出的错误类，继承自 AxiosError 类。

Cancel CanceledError 的别名

Cancel 类是 CanceledError 类的别名，为向后兼容而保留导出，将在未来版本中移除。

isCancel

检查某个错误是否为 CanceledError 的函数，可用于区分主动取消和意外错误。

isCancel(value: any): boolean;

import axios from "axios";

const controller = new AbortController();

axios.get("/api/data", { signal: controller.signal }).catch((error) => {
  if (axios.isCancel(error)) {
    console.log("Request was cancelled:", error.message);
  } else {
    console.error("Unexpected error:", error);
  }
});

controller.abort("User navigated away");

isAxiosError

检查某个错误是否为 AxiosError 的函数。在 catch 块中使用此函数，可安全访问 axios 特有的错误属性，如 error.response 和 error.config。

isAxiosError(value: any): value is AxiosError;

import axios from "axios";

try {
  await axios.get("/api/resource");
} catch (error) {
  if (axios.isAxiosError(error)) {
    // error.response、error.config、error.code 均可使用
    console.error("HTTP error", error.response?.status, error.message);
  } else {
    // 非 axios 错误（例如编程错误）
    throw error;
  }
}

all 已废弃，请改用 Promise.all

all 函数接受一组 Promise 并返回一个在所有 Promise 都完成后才完成的单一 Promise，现已废弃，推荐使用 Promise.all 方法。

从 0.22.0 版本起，all 函数已废弃，将在未来版本中移除。建议改用 Promise.all 方法。

spread

spread 函数可将一个参数数组展开为函数调用的多个参数，在你需要将数组参数传递给接收多个参数的函数时非常实用。

spread<T, R>(callback: (...args: T[]) => R): (array: T[]) => R;

toFormData

将普通 JavaScript 对象（包括嵌套对象）转换为 FormData 实例，在需要从对象中以编程方式构建 multipart 表单数据时非常实用。

toFormData(sourceObj: object, formData?: FormData, options?: FormSerializerOptions): FormData;

import { toFormData } from "axios";

const data = { name: "Jay", avatar: fileBlob };
const form = toFormData(data);
// form 现在是一个可直接发送的 FormData 实例
await axios.post("/api/users", form);

formToJSON

将 FormData 实例转换回普通 JavaScript 对象，在需要以结构化格式读取表单数据时非常实用。

formToJSON(form: FormData): object;

import { formToJSON } from "axios";

const form = new FormData();
form.append("name", "Jay");
form.append("role", "admin");

const obj = formToJSON(form);
console.log(obj); // { name: "Jay", role: "admin" }

getAdapter

通过名称或名称数组解析并返回一个适配器函数。axios 在内部使用此函数为当前环境选择最合适的适配器。

getAdapter(adapters: string | string[]): AxiosAdapter;

import { getAdapter } from "axios";

// 显式获取 fetch 适配器
const fetchAdapter = getAdapter("fetch");

// 按优先级列表获取最合适的适配器
const adapter = getAdapter(["fetch", "xhr", "http"]);

mergeConfig

合并两个 axios 配置对象，使用与 axios 内部合并默认配置和请求级选项相同的深度合并策略。后者的值优先级更高。

mergeConfig<T>(config1: AxiosRequestConfig<T>, config2: AxiosRequestConfig<T>): AxiosRequestConfig<T>;

import { mergeConfig } from "axios";

const base = { baseURL: "https://api.example.com", timeout: 5000 };
const override = { timeout: 10000, headers: { "X-Custom": "value" } };

const merged = mergeConfig(base, override);
// { baseURL: "https://api.example.com", timeout: 10000, headers: { "X-Custom": "value" } }

常量

HttpStatusCode

包含 HTTP 状态码命名常量的对象，可用于编写更具可读性的条件判断，避免直接使用数字字面量。

import axios, { HttpStatusCode } from "axios";

try {
  const response = await axios.get("/api/resource");
} catch (error) {
  if (axios.isAxiosError(error)) {
    if (error.response?.status === HttpStatusCode.NotFound) {
      console.error("Resource not found");
    } else if (error.response?.status === HttpStatusCode.Unauthorized) {
      console.error("Authentication required");
    }
  }
}

其他

VERSION

axios 包的当前版本号字符串，随每次发布更新。