@uni-helper/axios-adapter

适用于 Vue2 和 Vue3 的 uniapp Axios 适配器

目录

• 简介
• 平台兼容性
• 安装
• 快速开始
• 使用
  • 创建自定义实例
  • 与 useAxios 一起使用
  • 上传和下载
  • 小程序
• API 参考
• 版本策略
• 参与贡献
• 许可证

简介

@uni-helper/axios-adapter 封装了 uni-app 的 uni.request、uni.downloadFile、uni.uploadFile 等接口，让开发者可以在 uni-app 的各类平台上继续使用熟悉的 axios 编程范式。适配器同时为 TypeScript 项目提供全局类型扩展，补充 upload、download 以及 uni-app 专有请求参数的类型定义。

平台兼容性

| Vue 版本 | 支持情况 | | -------- | -------- | | Vue 2 | √ | | Vue 3 | √ |

| App | 快应用 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节小程序 | QQ 小程序 | | ---------------------------------------- | ------ | ---------- | ------------ | ---------- | ---------- | --------- | | HBuilderX 3.4.8app-vueapp-nvue | √ | √ | √ | √ | √ | √ |

| 钉钉小程序 | 快手小程序 | 飞书小程序 | 京东小程序 | | ---------- | ---------- | ---------- | ---------- | | √ | √ | √ | √ |

| H5-Safari | Android Browser | 微信浏览器(Android) | QQ 浏览器(Android) | Chrome | IE | Edge | Firefox | PC-Safari | | --------- | --------------- | ------------------- | ------------------ | ------ | --- | ---- | ------- | --------- | | √ | √ | √ | √ | √ | √ | √ | √ | √ |

安装

pnpm i @uni-helper/axios-adapter axios

适配器与 axios 的版本需要保持主版本号和次版本号一致。当前适配器版本为 1.18.0，推荐搭配 axios@^1.18.0 使用。

快速开始

import { createUniAppAxiosAdapter } from '@uni-helper/axios-adapter'
import axios from 'axios'

axios.defaults.adapter = createUniAppAxiosAdapter()

配置完成后，即可像往常一样使用 axios.get、axios.post 等方法发起请求。

使用

创建自定义实例

import { createUniAppAxiosAdapter } from '@uni-helper/axios-adapter'
import axios from 'axios'

const instance = axios.create({ adapter: createUniAppAxiosAdapter() })

与 useAxios 一起使用

import { createUniAppAxiosAdapter } from '@uni-helper/axios-adapter'
import axios from 'axios'

axios.defaults.adapter = createUniAppAxiosAdapter()
const { data, isFinished } = useAxios('/posts')

上传和下载

// 下载
axios.download('/')
// or
axios.request({
  url: '/',
  method: 'download',
})

// 上传
axios.upload('/', new File([new Blob()], 'fake file'))
// or
axios.request({
  url: '/',
  method: 'upload',
  data: new File([new Blob()], 'fake file'),
})

小程序

自 axios 1.4.0 开始，axios 已对小程序环境做了兼容处理。若仍需在小程序中使用 FormData 和 Blob，可安装对应的 polyfill 并启用构建插件：

pnpm add miniprogram-formdata miniprogram-blob

// vite.config.js
import uniAxiosAdapter from '@uni-helper/axios-adapter/vite'

export default {
  plugins: [
    uniAxiosAdapter()
  ]
}

如果你使用的是 Vue CLI，改用 @uni-helper/axios-adapter/webpack 即可。

API 参考

createUniAppAxiosAdapter(options?: UserOptions): AxiosAdapter

创建适配器实例，可直接赋值给 axios.defaults.adapter 或 axios.create({ adapter })。

• options：可选配置对象，当前版本支持扩展 uni-app 请求参数（参见 globalExtensions.ts 中的类型定义）。
• 返回值：标准的 AxiosAdapter 函数。

axios.upload<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>

以 uni.uploadFile 发送上传请求，data 通常为 FormData 实例。

axios.download<T>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>

以 uni.downloadFile 发起下载请求，返回的 response.data 默认为文件临时路径或 Buffer（取决于运行环境）。

版本策略

自 1.4.0 开始，请始终保持主版本号和次版本号与 axios 一致。例如当你安装了 1.5.1 版本时，你可以安装 axios 的 1.5.x 版本。这样做的目的是确保适配器始终支持最新的 axios 特性。

参与贡献

欢迎通过 Issue 或 Pull Request 参与改进本项目。开始前请阅读 CONTRIBUTING.md，了解本地开发、测试、提交规范与架构说明。

许可证

MIT