Axios

axios 是一个基于 Promise 的 HTTP 客户端，可用于浏览器和 Node.js。

Installation

npm

npm i axios

yarn

yarn add axios

pnpm

pnpm add axios

bun

bun add axios

Quick Start

GET

import axios from 'axios'

type User = { id: number; name: string }

const { data } = await axios.get<User>('https://example.com/api/users/1')

POST

import axios from 'axios'

type CreateUserBody = { name: string }
type CreateUserResp = { id: number }

const body: CreateUserBody = { name: 'Alice' }
const { data } = await axios.post<CreateUserResp>(
  'https://example.com/api/users',
  body
)

Instance（推荐）

import axios from 'axios'

export const api = axios.create({
  baseURL: 'https://example.com/api',
  timeout: 10_000,
  headers: {
    'Content-Type': 'application/json'
  }
})

常用 defaults

api.defaults.baseURL = 'https://example.com/api'
api.defaults.timeout = 10_000
api.defaults.headers.common.Authorization = 'Bearer token'

Request Config 速查

await api.request({
  url: '/users',
  method: 'GET',
  params: { page: 1, pageSize: 20 },
  headers: { 'X-Trace-Id': 'xxx' },
  timeout: 10_000,
  responseType: 'json',
  withCredentials: false
})

Response 结构

import type { AxiosResponse } from 'axios'

type User = { id: number; name: string }

const res: AxiosResponse<User> = await api.get<User>('/users/1')
const user: User = res.data

Interceptors

请求拦截：统一加 Token

import axios from 'axios'

const requestInterceptorId = api.interceptors.request.use((config) => {
  const token = localStorage.getItem('token') ?? ''
  if (token) {
    config.headers = config.headers ?? {}
    config.headers.Authorization = `Bearer ${token}`
  }
  return config
})

api.interceptors.request.eject(requestInterceptorId)

响应拦截：统一取 data

api.interceptors.response.use((response) => response.data)

如果你做了 “response.data 解包”，那么后续返回值不再是 AxiosResponse，而是你的业务数据类型。

错误处理

import axios from 'axios'

try {
  await api.get('/users/1')
} catch (err) {
  if (axios.isAxiosError(err)) {
    const status = err.response?.status
    const data = err.response?.data
    const message = err.message
  } else {
    throw err
  }
}

取消请求（AbortController）

const controller = new AbortController()

const p = api.get('/users', { signal: controller.signal })

controller.abort()
await p

上传文件（FormData）

const form = new FormData()
form.append('file', file)
form.append('name', 'avatar')

await api.post('/upload', form, {
  onUploadProgress: (e) => {
    const total = e.total ?? 0
    const percent = total ? Math.round((e.loaded / total) * 100) : 0
  }
})

并发请求

const [a, b] = await Promise.all([api.get('/a'), api.get('/b')])