
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.uploadFile和uni.downloadFile,支持进度回调 - 请求取消:v4 引入
signal和createCancelSource()跨平台取消机制 - 全平台兼容:微信/支付宝/百度/抖音/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
配置层级#
const http = createLuchRequest({
baseURL: 'https://api.example.com',
timeout: 10_000,
header: { Accept: 'application/json' },
validateStatus: (status) => status >= 200 && status < 300
})
| 配置 | 说明 |
|---|---|
baseURL | 基础 URL,与请求 url 拼接 |
method | HTTP 方法,默认 GET |
header | 请求头,大小写不敏感合并 |
params | URL 查询参数 |
paramsSerializer | 自定义参数序列化 |
timeout | 超时时间(ms) |
validateStatus | 状态码校验函数 |
signal | 取消信号 |
nativeOptions | 透传平台原生参数 |
luchMeta | 用户自定义元数据(拦截器中可访问) |
审核规范#
luch-request 是工具库,不涉及平台审核。但使用时需注意:
- 请求域名必须在小程序后台 request 合法域名 列表中(各平台通用要求)
- 上传/下载域名需分别配置在 uploadFile / downloadFile 合法域名 中
- HTTPS 是所有小程序平台的强制要求(开发环境可关闭校验)
开发指南#
快速上手#
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 }
})
拦截器#
// 请求拦截器(支持 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)
})
上传文件#
// 上传单个文件
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)#
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()
常见陷阱#
- 拦截器必须 return config/response — 忘记 return 会导致请求挂起
- header 合并是大小写不敏感的 —
Content-Type和content-type视为同一个 header - v4 只提供 ESM — 不支持 CommonJS require(),需确保构建工具支持 ESM
- upload/download 不继承实例 method — 只有普通 request 继承实例默认 method
- validateStatus 默认只接受 200-299 — 需要 304/4xx 等走响应拦截器而非错误拦截器时,需自定义
- 拦截器中修改 header 需返回新对象 — 直接修改 config.header 属性可能不生效(合并策略)
生态资源#
相关工具#
| 工具 | 说明 |
|---|---|
| alova | 请求策略层框架,20+ 请求策略(分页/表单/上传/SSE) |
| uni-network | uni-helper 出品的 HTTP 客户端(127⭐) |
| axios-adapter | uni-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 运行时)
社区资源#
- GitHub Issues — 0 open issues(维护良好)
- npm 包:luch-request
版本更新#
v4.0.0-alpha.1(2026-08-04)#
- TypeScript-first 重写:完全用 TypeScript 编写
- ESM-only:只提供 ES Module 产物(ES2017 语法)
- 全新 API:
createLuchRequest()工厂函数替代类构造器 - 取消机制:
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) |