更新记录

1.0.1（2026-10-28）

增加示例工程。

1.0.0（2026-10-28）

建立统一任务 API、并发队列、订阅、持久化、暂停/恢复、取消及手动/自动重试。
小程序/Web 接入 uni 上传下载、进度和取消；没有后台运行或原生续传能力。

平台兼容性

uni-app(5.24)

Vue2	Vue3	Chrome	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
√	√	×	×	√	√	√	√	√

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
√	√	√	√	√	√	√	√	√	√	√	√

uni-app x(5.24)

Chrome	Safari	Android	iOS	鸿蒙	微信小程序
×	×	√	√	√	√

其他

多语言	暗黑模式	宽屏模式	蒸汽模式
×	×	×	√

umi-file-transfer

uni-app x 文件上传、下载和任务管理 UTS 插件。推荐 HBuilderX 5.31+。

平台能力

能力	Android	iOS	HarmonyOS 应用	鸿蒙元服务	微信 / 支付宝小程序
上传 / 下载 / 进度	支持	支持	支持	API 11+	支持
取消 / 手动重试	支持	支持	支持	支持	支持
下载断点续传	支持	支持	支持	暂不提供	暂不提供
上传断点续传	tus 1.0.0	tus 1.0.0	tus 1.0.0（仅前台）	暂不提供	暂不提供
后台运行中的传输	支持	支持	支持	支持	不保证
队列 / 订阅 / 状态缓存	支持	支持	支持	支持	支持

上述能力尚未完成各端编译和真机验证。Web 受 CORS 与浏览器生命周期限制。其他小程序只有在所用 uni-app 编译器支持相应网络 API 时才能使用；本工程小程序配置范围为微信、支付宝。

示例页面默认下载 https://proof.ovh.net/files/10Mb.dat（10485760 字节），支持 Range、ETag 和 Last-Modified。支持上传、下载续传的平台默认开启续传。使用默认地址创建续传上传时，页面读取本地文件大小，向 https://tusd.tusdemo.net/files/ 创建独立资源，再将返回的资源地址交给插件；恢复沿用同一资源并查询服务端偏移。关闭续传时，普通上传仍使用 Cloudflare 测速接口。鸿蒙上传续传请关闭后台传输。公共测试服务仅用于非敏感样本，资源可能被服务端清理。

自定义上传地址需填写服务端预创建的 tus 资源地址。切换页面开关或更改默认地址不会改变已有任务的配置，请重新创建任务测试。服务端不支持续传时，下载可能从头开始。

使用

import { getTransferManager, TransferTask } from '@/uni_modules/umi-file-transfer'

const manager = getTransferManager()
const capabilities = manager.getCapabilities()
manager.setConcurrency(2)
const unsubscribe = manager.subscribe((tasks: TransferTask[]) => {
  console.log(tasks)
})

const id = manager.create({
  kind: 'download',
  url: 'https://your-domain.example/archive.zip',
  background: capabilities.background,
  resumable: capabilities.resumeDownload,
  maxRetries: 2
})

// iOS 校验失败时返回空字符串，不会创建任务。
if (id.length == 0) console.error(manager.getLastError())

manager.pause(id)
manager.resume(id)
manager.cancel(id)
manager.retry(id)
console.log(manager.get(id))
console.log(manager.list())
// 页面销毁只取消订阅，不终止应用级传输。
unsubscribe()
// 不再需要记录时调用；已下载的完整文件仍保留。
manager.remove(id)

在 App.uvue 的 onLaunch 中调用 getTransferManager()。页面通过 subscribe 获取完整列表，记得在 onUnload 调用返回的取消订阅函数。

普通上传

const uploadId = manager.create({
  kind: 'upload',
  url: 'https://your-domain.example/upload',
  filePath: '/absolute/app/sandbox/photo.jpg',
  name: 'file',
  headers: { 'Authorization': 'Bearer ...' },
  formData: { 'folder': 'photos' },
  background: capabilities.background,
  maxRetries: 0
})

普通上传是 POST multipart/form-data。暂停、重试会重新上传，服务端应按业务 ID 去重。原生端路径必须指向应用可读的真实文件；content://、相册资源、临时授权 URI 应先复制进应用沙盒。小程序使用其平台认可的临时文件路径。插件不会主动弹出文件选择器或申请相册权限。

上传断点续传（Android / iOS / 鸿蒙应用）

const uploadId = manager.create({
  kind: 'upload',
  // 这是业务服务器事先创建好的 tus 上传资源地址，不是创建资源的入口。
  url: 'https://your-domain.example/uploads/existing-resource-id',
  filePath: '/absolute/app/sandbox/archive.zip',
  resumable: true,
  background: capabilities.backgroundResumeUpload,
  maxRetries: 2
})

上传续传需要服务端支持 tus 1.0.0，并提供已创建的上传资源地址。

资源创建、鉴权刷新、资源删除由业务服务器管理。必须保证资源 ID 绑定同一份本地文件，不能在暂停期间修改源文件。tus 上传不接收 formData，元信息应在创建资源时设置。取消本地任务不会删除服务端 tus 资源。

iOS 上传续传需要额外磁盘空间，准备阶段需保持应用运行。鸿蒙应用上传续传仅支持前台运行，服务端还需支持 POST + X-HTTP-Method-Override: PATCH；同时传入 background: true 会抛错。元服务和小程序暂不支持上传续传。

API

方法	说明
`getCapabilities()`	平台名称、后台、上传/下载续传、`backgroundResumeUpload` 与 multipart 能力以及说明
`create(options)`	创建并进入队列，返回任务 ID；iOS 非法配置返回空字符串，其他平台同步抛错
`getLastError()`	最近一次 create / resume / retry 的校验错误；每次调用这三个方法时重置。iOS 使用此方法获取错误说明
`list()` / `get(id)`	查询任务副本；不存在时 `get` 返回 null
`subscribe(listener)`	立即返回当前列表，后续变化时通知；返回取消订阅函数
`pause(id)`	保留可续传数据；不支持续传的平台恢复时从头传输
`resume(id)`	将暂停/失败/取消任务重新入队；任务不存在时 iOS 记录 getLastError()，其他平台抛错
`cancel(id)`	停止并清理可清理的本地续传数据，保留任务记录
`retry(id)`	重新入队并重置自动重试次数；任务不存在的错误处理同 resume；可用续传数据按平台保留
`remove(id)`	停止任务并移除元数据；不删除已完成文件或源文件
`setConcurrency(value)`	并发数 1–6，默认 2；降低时不打断已运行任务

create 参数

字段	默认值	说明
`url`	必填	HTTPS 资源地址；Android 和鸿蒙普通传输不支持重定向，其他传输遵循系统策略
`kind`	必填	`upload` 或 `download`
`filePath`	空字符串	上传必填；下载由插件决定保存位置
`name`	`file`	multipart 文件字段名
`headers`	`{}`	请求头，所有值必须为字符串
`formData`	`{}`	multipart 文本字段，所有值必须为字符串；tus 模式不可使用
`background`	`false`	明确请求原生后台传输，不支持的平台抛错
`resumable`	`false`	请求断点续传，不支持的平台抛错
`maxRetries`	`0`	自动重试次数，上限 10；普通上传建议 0 或服务端提供去重

状态与进度

queued → running → completed / failed；运行、排队或失败任务可暂停为 paused；取消为 canceled。恢复和重试重新进入 queued。自动重试处理尚未取得 HTTP 响应的失败（包含部分本地错误）、408、429、5xx，等待 2、4、8…秒，上限 60 秒；其他 HTTP 错误需要业务处理后手动重试。不会自动刷新鉴权或遵循 Retry-After。

TransferTask 含 id、原始参数、state、bytes、total、progress、statusCode、response、error、retries、maxRetries、createdAt、updatedAt、retryAt。时间为毫秒时间戳。未知大小时 total = 0，不应据此推算剩余时间；只有 state = completed 表示服务器完成确认。下载成功后 filePath 是本地结果路径。iOS multipart 的字节进度包括封装体；其他原生上传进度通常为文件字节。原生响应体最多保存约 64K 文本；鸿蒙当前不提供响应体（response 为空，暂未生效）。

Android/鸿蒙下载保存在应用私有目录，iOS 保存在 Application Support；小程序/Web 下载结果是平台临时路径，业务需要长期保存时应调用平台文件保存 API。移除记录不删除完整结果文件，业务自行清理。

使用限制

后台传输仅适用于已经开始的任务。应用挂起时，不保证启动排队任务或执行自动重试；回到前台后同步任务状态。
Android 后台传输应从可见页面中的用户操作启动。Android 13+ 通知授权由宿主按业务申请。后台传输可能因系统运行时限或进程回收而中断；再次打开应用后可手动恢复。
iOS 普通切后台可继续传输；强制退出应用、系统调度或磁盘清理可能导致中断。无法续传时会重新下载。当前不保证应用被系统唤醒后立即发送任务事件，再次打开应用后可查询任务状态。
鸿蒙元服务需 API 11+、系统文件传输能力和网络权限，暂不支持断点续传；暂停后恢复会重新传输。
小程序不保证退出后的传输。合法域名、文件大小和后台运行限制以目标平台要求为准。
下载断点续传需要服务端支持 Range 请求和文件版本校验；条件不满足时可能重新下载。
请求头随任务保存在应用沙盒，包括鉴权信息；退出账号后应移除相关任务记录。过期签名 URL 需要创建新任务。

验证

npm install
npm test
npm run check

以上检查不能替代各平台编译和真机验证。

尚需在 HBuilderX 分别编译 Android、iOS、鸿蒙和目标小程序，并完成：真实文件上传下载、HTTP 错误、离线恢复、暂停后快速恢复、取消后的迟到回调、忽略 Range / ETag 变化 / 416、tus 偏移冲突、磁盘不足、锁屏与切后台、进程终止后的任务重建、通知拒绝、鸿蒙元服务和小程序真机限制。当前未完成这些真机验收。