Skip to content
Axios 概述
一个简单的 Axios 请求示例
一个最常见的 GET 请求是这样写的：
js
import axios from 'axios';
axios.get('/api/users', {
params: { page: 1, size: 10 }
}).then(response => {
console.log(response.data);
});axios.get(url, config) 返回一个 Promise。config 中的 params 对象会被序列化并拼接到 URL 上，所以实际请求的地址是 /api/users?page=1&size=10。请求成功时，response.data 是服务端返回的数据。
POST 请求的写法类似 [2]：
js
axios.post('/api/users', {
name: '张三',
email: 'zhangsan@example.com'
}).then(response => {
console.log(response.status); // 状态码，例如 201 Created
});axios.post(url, data, config) 的第二个参数作为请求体发送。默认情况下，普通对象会先被序列化为 JSON 字符串，并自动设置 Content-Type: application/json [5][9]。
成功响应会被包装成一个固定结构的对象 [3]：
js
{
data: {}, // 服务端返回的响应体
status: 200, // HTTP 状态码
statusText: 'OK', // 状态文本
headers: {}, // 响应头
config: {}, // 本次请求的配置
request: {} // 底层请求对象
}其中 request 在浏览器中是 XMLHttpRequest 实例，在 Node.js 中是 ClientRequest 实例。
默认情况下，当响应状态码不在 2xx 范围内时，Promise 会进入 rejected，抛出的错误对象是 AxiosError。axios 把错误划分成几个分支 [7]：
js
axios.get('/api/users/404')
.catch(error => {
if (error.response) {
// 服务器返回了非 2xx 状态码
console.log(error.response.status);
console.log(error.response.data);
} else if (error.request) {
// 请求已发出，但没有收到响应（如超时、断网）
console.log(error.request);
} else {
// 请求配置阶段出错
console.log(error.message);
}
});请求被主动取消时也会进入 catch，可以通过 error.code === 'ERR_CANCELED' 与其他错误区分 [8]。
Axios 的定位：基于 Promise 的 HTTP 客户端
Axios 官方仓库对自己的定义是：一个基于 Promise 的 HTTP 客户端，适用于浏览器和 Node.js [1]。
这个定位可以从两个层面理解。
第一，它解决的是“发 HTTP 请求”的问题，并且把两种运行环境统一起来。在浏览器中，axios 使用 XMLHttpRequest 发送请求；在 Node.js 中，它使用内置的 http/https 模块发送请求 [1]。调用方不感知底层差异。
第二，每个请求方法都返回 Promise。原生 XHR 的异步结果通过事件回调传递，axios 则统一走 then/catch，或者配合 ES6 的 async/await：
js
async function loadUsers() {
const response = await axios.get('/api/users');
return response.data;
}在 ES6 项目中，axios 通常作为一个独立请求层存在。业务代码不直接接触 XHR 或 fetch，而是通过 axios 的实例和拦截器统一处理请求细节。
核心能力一览
除了通用的 Promise API，axios 的核心能力还包括：请求/响应拦截器、请求/响应数据转换、请求取消、自动 JSON 转换、客户端 XSRF 防护，以及上传/下载进度事件 [1]。下面介绍其中与日常使用关系最紧密的几项。
实例与默认配置
axios.create(config) 用于创建一个独立的实例。实例拥有自己的默认配置，并带有 get、post、put、patch、delete 等请求方法 [4]：
js
const http = axios.create({
baseURL: 'https://api.example.com',
timeout: 5000,
headers: { 'X-Client': 'web' }
});
http.get('/users');
// 实际请求：https://api.example.com/users设置 baseURL 后，请求方法中的相对路径会拼接到 baseURL 后面；timeout 对该实例下的所有请求生效。多个实例之间互不影响，适合同时对接多个服务。
全局对象上的 axios.defaults 也可以修改默认配置，但全局配置会被所有请求共享，容易互相影响。项目里更常见的是用 axios.create 隔离各自的配置。
请求与响应拦截器
拦截器是在请求发送前、响应返回后插入的自定义逻辑 [6]：
js
const http = axios.create({ baseURL: '/api' });
http.interceptors.request.use(config => {
const token = localStorage.getItem('token');
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
});
http.interceptors.response.use(
response => response.data,
error => Promise.reject(error)
);第一个拦截器在每个请求发送前读取 token 并写入请求头；第二个拦截器把 response.data 作为成功值返回，后续 http.get(...) 拿到的就是响应体本身。
注意点：
- 拦截器的 fulfilled 回调必须返回
config或response，否则后续链路拿不到数据。 - 注册多个请求拦截器时，执行顺序与注册顺序相反（后注册的先执行）；响应拦截器则按注册顺序执行。
- 响应拦截器的 rejected 分支适合做统一错误处理，例如 401 时跳转登录页。
请求取消
Axios 1.x 推荐通过 Web 标准的 AbortController 取消请求 [8]：
js
const controller = new AbortController();
axios.get('/api/files/1', {
signal: controller.signal
});
// 用户点击取消按钮时调用
controller.abort();调用 abort() 后，对应请求的 Promise 会变为 rejected，错误对象的 code 为 ERR_CANCELED。
说明：早期版本提供的 CancelToken 仍然可以工作，但从 1.x 开始已被官方标记为弃用，新代码应优先使用 signal [8][10]。
自动 JSON 转换
Axios 默认会对 JSON 做双向转换 [5][9]：
- 发送请求时，
data中的普通对象会序列化为 JSON 字符串； - 收到响应时，会尝试把响应体字符串解析为 JavaScript 对象；解析失败则保留原始字符串。
js
const response = await axios.post('/api/login', {
username: 'user',
password: '123456'
});
// response.data 已经是一个对象
console.log(response.data.token);如果默认行为不满足需求，可以通过请求配置中的 transformRequest 和 transformResponse 替换转换逻辑。
适配器与跨平台
适配器是 axios 内部真正发起网络请求的模块。axios 根据运行环境选择适配器 [1][5]：
- 浏览器端默认使用 XMLHttpRequest 适配器；
- Node.js 端默认使用 http/https 适配器；
- 从 v1.7.0 起引入 fetch 适配器，当 xhr/http 适配器不可用或不被环境支持时作为默认，也可以通过
adapter: 'fetch'显式指定 [10]。
适配器返回的也是 Promise，所以上层 API 不依赖具体网络实现。这也是 axios 能在浏览器和 Node.js 中共用同一套接口的原因。
与 Fetch API 的简单对比
Fetch API 是浏览器原生提供的请求方案，与 axios 的差异主要体现在几个方面：
| 对比项 | Axios | Fetch API |
|---|---|---|
| JSON 处理 | 自动序列化与解析 | 需要手动调用 response.json() |
| HTTP 错误状态 | 非 2xx 时 Promise 变为 rejected | 遇到网络级错误时 Promise 才 reject；HTTP 4xx/5xx 仍 resolve |
| 拦截器 | 内置请求、响应拦截器 | 没有原生拦截器 |
| 请求取消 | 支持 signal | 支持 signal |
| 上传/下载进度 | 提供 onUploadProgress / onDownloadProgress | 没有原生上传进度事件，下载进度需自行基于 Stream 计算 |
Fetch 的错误处理语义值得注意：它把 4xx/5xx 也视为“成功响应”，调用方需要手动检查 response.ok 或 response.status 判断业务是否成功；axios 默认把非 2xx 状态码直接映射为 rejected 的 Promise。
选择上没有绝对标准。偶尔调用一两个接口时，fetch 足够直接；请求逻辑复杂、需要统一错误处理、注入认证信息、监听进度时，axios 的开箱能力更省事。
运行环境支持范围
浏览器端
在浏览器中，axios 默认基于 XMLHttpRequest。这意味着：
- 支持所有提供 XHR 的主流浏览器；在未原生支持 Promise 的旧浏览器中，需要额外引入 Promise polyfill；
- 响应对象中的
request字段是 XMLHttpRequest 实例 [3]； onUploadProgress和onDownloadProgress可以用于文件上传、下载进度展示 [1]。
Node.js 端
在 Node.js 中，axios 默认使用内置的 http/https 模块：
- 不依赖第三方网络库；
- 响应对象中的
request字段是 ClientRequest 实例 [3]； - 浏览器端使用的配置项、拦截器、实例方法在 Node.js 中同样可用。
两种环境的主要差异集中在底层适配器与 request 字段类型；对业务调用方来说，API 是一致的。
| 维度 | 浏览器 | Node.js |
|---|---|---|
| 默认适配器 | XMLHttpRequest | http/https |
| response.request 类型 | XMLHttpRequest 实例 | ClientRequest 实例 |
| 上传/下载进度 | 支持 | 支持 |
Axios 目前仍是活跃维护的开源项目，当前稳定版本为 1.x [1]。功能演进以官方仓库和发布说明为准。
在项目中的角色
Axios 在项目中通常承担“统一请求入口”的职责。它适合集中处理以下几类问题：
- 统一设置
baseURL、超时、请求头； - 在拦截器中集中注入认证凭证；
- 对服务端返回的数据统一解包；
- 把非 2xx 状态码统一收口到错误处理逻辑。
一种常见的组织方式是创建独立的请求模块，只导出封装后的实例：
js
// api/http.js
import axios from 'axios';
const request = axios.create({
baseURL: '/api',
timeout: 10000
});
request.interceptors.request.use(config => {
const token = localStorage.getItem('token');
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
});
request.interceptors.response.use(
response => response.data,
error => {
if (error.response && error.response.status === 401) {
window.location.href = '/login';
}
return Promise.reject(error);
}
);
export default request;这个例子面向浏览器环境；在 Node.js 中使用时，localStorage 和 window 需要替换为对应实现。
业务代码不直接依赖全局 axios，也不需要关心 token 的来源：
js
import request from './api/http';
const user = await request.get('/users/1');由于响应拦截器已经返回了 response.data，业务侧拿到的就是数据本身。请求代码集中到一个模块后，接口前缀、认证方式、错误提示的调整都只涉及一个文件。
下一步与学习路线
本篇是系列的第 1 篇，只完成了对 Axios 定位与总体特性的介绍。后续文章会展开：
- Axios 核心概念与请求流程：默认配置的合并规则、拦截器调用链、请求与响应转换时机；
- 请求取消与错误识别的完整分支；
- 在具体前端框架中的接入方式。
如果现在就想继续深入，可以对照官方 README [1] 和请求配置文档 [9] 中的内容，逐个验证本文提到的特性。