# npm
npm install axios
 
# yarn
yarn add axios
 
# pnpm
pnpm add axios
 
# CDN（浏览器直接使用）
<script src="https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js"></script>

import axios from 'axios'
 
// 创建自定义实例，配置默认值
const instance = axios.create({
  baseURL: 'https://api.example.com',
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json',
  },
  // 自动将响应体解析为 JSON
  responseType: 'json',
  // 只有状态码在 2xx 范围内才不会触发错误
  validateStatus: (status) => status >= 200 && status < 300,
})
 
// 请求拦截器：在请求发送前统一处理
instance.interceptors.request.use(
  (config) => {
    // 自动附加 Token
    const token = localStorage.getItem('token')
    if (token) {
      config.headers.Authorization = `Bearer ${token}`
    }
    return config
  },
  (error) => Promise.reject(error)
)
 
// 响应拦截器：统一处理响应和错误
instance.interceptors.response.use(
  (response) => response.data,
  (error) => {
    if (error.response?.status === 401) {
      // 处理未授权
      window.location.href = '/login'
    }
    return Promise.reject(error)
  }
)

import axios from 'axios'
 
// GET 请求
const { data } = await axios.get('https://api.example.com/users')
console.log(data)
 
// POST 请求
const result = await axios.post('https://api.example.com/users', {
  name: '张三',
  email: '[email protected]',
})
 
// 带参数的请求
const users = await axios.get('/users', {
  params: { role: 'admin', page: 1 },
})

// 请求拦截器
axios.interceptors.request.use((config) => {
  config.headers['X-Request-Time'] = Date.now()
  return config
})
 
// 响应拦截器
axios.interceptors.response.use(
  (response) => response,
  (error) => {
    // 全局错误处理
    return Promise.reject(error)
  }
)

// AbortController（现代方式）
const controller = new AbortController()
axios.get('/api/data', { signal: controller.signal })
controller.abort() // 取消请求
 
// CancelToken（传统方式，已不推荐）
const source = axios.CancelToken.source()
axios.get('/api/data', { cancelToken: source.token })
source.cancel('请求已取消')

axios.post('/upload', formData, {
  onUploadProgress: (e) => {
    console.log(`上传进度: ${Math.round((e.loaded / e.total) * 100)}%`)
  },
  onDownloadProgress: (e) => {
    console.log(`下载进度: ${Math.round((e.loaded / e.total) * 100)}%`)
  },
})

axios.get('/api/slow', {
  timeout: 5000, // 5 秒超时
})

const [users, posts] = await axios.all([
  axios.get('/users'),
  axios.get('/posts'),
])
// 或使用 Promise.all
const results = await Promise.all([
  axios.get('/users'),
  axios.get('/posts'),
])

// 使用 Fetch Adapter（Axios 1.7+）
axios.get('/api/data', { adapter: 'fetch' })
 
// 使用 HTTP Adapter（Node.js）
axios.get('/api/data', { adapter: 'http' })
 
// 自定义 Adapter
axios.get('/api/data', {
  adapter: async (config) => {
    // 自定义请求逻辑
    return { data: {}, status: 200, statusText: 'OK', headers: {}, config }
  },
})

axios.post('/api/action', data, {
  xsrfCookieName: 'csrftoken',
  xsrfHeaderName: 'X-CSRFToken',
  withCredentials: true,
})

// 自定义请求转换
axios.post('/api', data, {
  transformRequest: [
    (data, headers) => {
      // 自定义序列化逻辑
      return JSON.stringify(data)
    },
    ...axios.defaults.transformRequest,
  ],
})

axios.get('/api/large-file', {
  maxContentLength: 50 * 1024 * 1024, // 限制 50MB
  maxBodyLength: 50 * 1024 * 1024,
})

interface User {
  id: number
  name: string
  email: string
}
 
// 泛型指定响应数据类型
const response = await axios.get<User>('/api/users/1')
const user: User = response.data
 
// 自定义请求配置类型
interface ApiConfig {
  showLoading?: boolean
  showError?: boolean
}
 
// 扩展 AxiosRequestConfig
declare module 'axios' {
  interface AxiosRequestConfig {
    showLoading?: boolean
    showError?: boolean
  }
}

// Vite - 无需额外配置，直接 import
import axios from 'axios'
 
// Webpack - 同上，直接 import
// Axios 会自动根据环境选择 Adapter
 
// 如需 Tree-shaking，使用具名导入
import { get, post } from 'axios' // 注意：Axios 默认导出，tree-shaking 效果有限

// .env
VITE_API_BASE_URL=https://api.example.com
VITE_API_TIMEOUT=10000
 
// src/api/index.ts
const api = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: Number(import.meta.env.VITE_API_TIMEOUT),
})

// src/api/request.ts - 统一请求层
import axios, { type AxiosRequestConfig, type AxiosResponse } from 'axios'
 
const request = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 15000,
})
 
// 请求拦截器
request.interceptors.request.use((config) => {
  // Token、Loading、日志等
  return config
})
 
// 响应拦截器
request.interceptors.response.use(
  (response: AxiosResponse) => {
    // 统一解包响应数据
    return response.data
  },
  (error) => {
    // 统一错误处理
    const status = error.response?.status
    const messages: Record<number, string> = {
      400: '请求参数错误',
      401: '未授权，请重新登录',
      403: '拒绝访问',
      404: '请求资源不存在',
      500: '服务器内部错误',
    }
    const message = messages[status] || `请求失败 (${status || '网络错误'})`
    console.error(message)
    return Promise.reject(error)
  }
)
 
// 导出封装后的方法
export const get = <T = any>(url: string, config?: AxiosRequestConfig) =>
  request.get<any, T>(url, config)
 
export const post = <T = any>(url: string, data?: any, config?: AxiosRequestConfig) =>
  request.post<any, T>(url, data, config)
 
export default request

// ❌ 不推荐：污染全局配置
axios.defaults.baseURL = 'https://api.example.com'
 
// ✅ 推荐：创建独立实例
const api = axios.create({ baseURL: 'https://api.example.com' })

// 在响应拦截器中集中处理所有错误
instance.interceptors.response.use(null, (error) => {
  if (axios.isCancel(error)) {
    console.log('请求已取消')
    return Promise.reject(error)
  }
 
  const status = error.response?.status
  switch (status) {
    case 401:
      // 跳转登录
      break
    case 403:
      // 提示无权限
      break
    case 429:
      // 限流处理
      break
    default:
      // 通用错误提示
      break
  }
  return Promise.reject(error)
})

let isRefreshing = false
let pendingRequests: Array<(token: string) => void> = []
 
instance.interceptors.response.use(null, async (error) => {
  if (error.response?.status === 401 && !error.config._retry) {
    if (isRefreshing) {
      // 等待 Token 刷新完成
      return new Promise((resolve) => {
        pendingRequests.push((token) => {
          error.config.headers.Authorization = `Bearer ${token}`
          resolve(instance(error.config))
        })
      })
    }
 
    error.config._retry = true
    isRefreshing = true
 
    try {
      const { data } = await axios.post('/auth/refresh', {
        refreshToken: localStorage.getItem('refreshToken'),
      })
      const newToken = data.token
      localStorage.setItem('token', newToken)
 
      // 重试所有等待的请求
      pendingRequests.forEach((cb) => cb(newToken))
      pendingRequests = []
 
      error.config.headers.Authorization = `Bearer ${newToken}`
      return instance(error.config)
    } finally {
      isRefreshing = false
    }
  }
  return Promise.reject(error)
})

const pendingRequests = new Map<string, AbortController>()
 
instance.interceptors.request.use((config) => {
  // 生成请求唯一标识
  const key = `${config.method}:${config.url}:${JSON.stringify(config.params)}`
 
  // 取消之前的相同请求
  if (pendingRequests.has(key)) {
    pendingRequests.get(key)!.abort()
  }
 
  const controller = new AbortController()
  config.signal = controller.signal
  pendingRequests.set(key, controller)
 
  return config
})
 
instance.interceptors.response.use((response) => {
  // 请求完成后移除
  const key = `${response.config.method}:${response.config.url}:${JSON.stringify(response.config.params)}`
  pendingRequests.delete(key)
  return response
})

# 使用精确版本或范围锁定
# package.json
{
  "dependencies": {
    "axios": "~1.18.0"   # 只允许 patch 更新
  }
}
 
# 定期运行安全审计
npm audit
# 或
pnpm audit