▶_MiniApp Toolkit

luch-request

工具

基于 Promise 的 uni-app 跨平台请求库,TypeScript 原生编写,体积小巧、API 易用、自定义能力强

uni-apprequesthttppromisetypescriptuploaddownload

详细文档

luch-request#

资源概述#

luch-request 是一个基于 Promise 开发的 uni-app 跨平台请求库,使用 TypeScript 原生编写。自 2019 年发布以来持续维护,是 uni-app 社区中使用最广泛的专用 HTTP 客户端之一。

核心特点:

  • TypeScript-first:v4.0 完全用 TypeScript 重写,提供完整类型定义
  • Promise-based:所有 API 返回 Promise,支持 async/await
  • 拦截器体系:request/response 拦截器,支持异步拦截
  • 上传/下载:封装 uni.uploadFileuni.downloadFile,支持进度回调
  • 请求取消:v4 引入 signalcreateCancelSource() 跨平台取消机制
  • 全平台兼容:微信/支付宝/百度/抖音/QQ/京东/小红书小程序 + H5 + App

项目数据(2026-08-07):

  • GitHub:667⭐ / 97 forks / MIT License
  • npm:稳定版 3.1.1 / v4 预发布 4.0.0-alpha.1 / 16 versions / 周下载 ~1,200
  • 活跃度:最后推送 2026-08-06(当日活跃),v4 alpha 发布 2026-08-04

设计规范#

API 设计哲学#

luch-request 遵循「小巧 + 易用 + 可扩展」原则:

  • 实例隔离createLuchRequest() 创建独立实例,配置和拦截器不共享
  • 配置合并策略:内置默认值 → 实例默认配置 → 单次请求配置(后者覆盖前者)
  • header 合并:大小写不敏感按名合并,单次值覆盖实例值
  • 不可变性:请求配置生成私有副本,防止拦截器污染 defaults

配置层级#

code
const http = createLuchRequest({
  baseURL: 'https://api.example.com',
  timeout: 10_000,
  header: { Accept: 'application/json' },
  validateStatus: (status) => status >= 200 && status < 300
})
配置说明
baseURL基础 URL,与请求 url 拼接
methodHTTP 方法,默认 GET
header请求头,大小写不敏感合并
paramsURL 查询参数
paramsSerializer自定义参数序列化
timeout超时时间(ms)
validateStatus状态码校验函数
signal取消信号
nativeOptions透传平台原生参数
luchMeta用户自定义元数据(拦截器中可访问)

审核规范#

luch-request 是工具库,不涉及平台审核。但使用时需注意:

  • 请求域名必须在小程序后台 request 合法域名 列表中(各平台通用要求)
  • 上传/下载域名需分别配置在 uploadFile / downloadFile 合法域名
  • HTTPS 是所有小程序平台的强制要求(开发环境可关闭校验)

开发指南#

快速上手#

code
import { createLuchRequest, isLuchRequestError, LuchRequestError } from 'luch-request'

// 1. 创建实例
const http = createLuchRequest({
  baseURL: 'https://api.example.com',
  timeout: 10_000
})

// 2. 发起 GET 请求
interface User { id: number; name: string }
try {
  const response = await http.get<User>('/users/1')
  console.log(response.data.id, response.data.name)
} catch (error) {
  if (isLuchRequestError(error)) {
    console.log(error.code, error.raw)
    if (error.code === LuchRequestError.ERR_CANCELED) {
      console.log('请求已取消')
    }
  }
}

// 3. POST 请求
const created = await http.post<{ id: number }>('/users', {
  data: { name: '张三', age: 25 }
})

拦截器#

code
// 请求拦截器(支持 async)
http.interceptors.request.use(async (config) => {
  // 添加 token
  const token = uni.getStorageSync('token')
  if (token) {
    config.header = { ...config.header, Authorization: `Bearer ${token}` }
  }
  return config
})

// 响应拦截器
http.interceptors.response.use((response) => {
  // 统一处理业务码
  if (response.data.code !== 0) {
    return Promise.reject(new Error(response.data.message))
  }
  return response
}, (error) => {
  // 统一错误处理
  if (isLuchRequestError(error)) {
    console.error(`请求失败: ${error.code}`)
  }
  return Promise.reject(error)
})

上传文件#

code
// 上传单个文件
const res = await http.upload<{ url: string }>('/upload', {
  filePath: tempFilePath,
  name: 'file',
  formData: { userId: '123' }
})

// 监听上传进度(v4)
const controller = new AbortController()
const res = await http.upload('/upload', {
  filePath: tempFilePath,
  name: 'file',
  signal: controller.signal,
  onTask: (task) => {
    task.onProgressUpdate((progress) => {
      console.log(`上传进度: ${progress.progress}%`)
    })
  }
})

请求取消(v4)#

code
import { createCancelSource, CancellationMode } from 'luch-request'

// 方式一:createCancelSource(推荐,跨平台)
const source = createCancelSource()
http.get('/slow-api', { signal: source.signal })
// 取消
source.cancel('用户取消了请求')

// 方式二:AbortController
const controller = new AbortController()
http.get('/data', { signal: controller.signal })
controller.abort()

常见陷阱#

  1. 拦截器必须 return config/response — 忘记 return 会导致请求挂起
  2. header 合并是大小写不敏感的Content-Typecontent-type 视为同一个 header
  3. v4 只提供 ESM — 不支持 CommonJS require(),需确保构建工具支持 ESM
  4. upload/download 不继承实例 method — 只有普通 request 继承实例默认 method
  5. validateStatus 默认只接受 200-299 — 需要 304/4xx 等走响应拦截器而非错误拦截器时,需自定义
  6. 拦截器中修改 header 需返回新对象 — 直接修改 config.header 属性可能不生效(合并策略)

生态资源#

相关工具#

工具说明
alova请求策略层框架,20+ 请求策略(分页/表单/上传/SSE)
uni-networkuni-helper 出品的 HTTP 客户端(127⭐)
axios-adapteruni-helper 的 axios 适配器(58⭐)
weapp-cookie小程序 Cookie 支持库(849⭐)

框架兼容性#

  • uni-app:原生支持(luch-request 基于 uni.request / uni.uploadFile / uni.downloadFile
  • Taro:不直接支持(Taro 使用 Taro.request),可参考 alova 的 Taro 适配器
  • 微信原生小程序:不直接支持(需 uni-app 运行时)

社区资源#

版本更新#

v4.0.0-alpha.1(2026-08-04)#

  • TypeScript-first 重写:完全用 TypeScript 编写
  • ESM-only:只提供 ES Module 产物(ES2017 语法)
  • 全新 APIcreateLuchRequest() 工厂函数替代类构造器
  • 取消机制signal + createCancelSource() 跨平台请求取消
  • 统一错误LuchRequestError + isLuchRequestError() 类型守卫
  • 配置体系nativeOptions 透传平台参数、luchMeta 自定义元数据
  • JSON 解析luchOptions.jsonParsing 控制 upload 响应解析
  • 不支持 uni-app x / UTS

v3.1.1(2023-08-02,稳定版)#

  • 基于 Promise 的经典版本
  • 支持 CommonJS / ESM
  • 实例级配置 + 拦截器
  • Request 类构造器方式

版本选择建议#

场景推荐版本
生产环境稳定优先v3.1.1(npm i luch-request
新项目 + TypeScript 深度使用v4 alpha(npm i luch-request@alpha
需要请求取消功能v4 alpha
CommonJS 环境v3.1.1(v4 仅 ESM)