更新记录

1.1.1（2026-08-30）

• 优化插件使用文档
• 更新插件市场展示及销售信息

1.1.0（2026-08-30）

新增

• 新增 HarmonyOS（app-harmony）平台实现：纯 UTS 编写（编译为 ArkTS），基于 @ohos.file.fs 读取文件、@ohos.net.http 发送分块、@ohos.security.cryptoFramework 计算文件 MD5
• 新增 utssdk/app-harmony/module.json5，声明 ohos.permission.INTERNET 网络权限

变更

• package.json 平台矩阵：uni-app x 的 android / ios / harmony 标记为 y（此前已有 Android/iOS 实现，标记与事实不符）

说明

• 鸿蒙端行为与 Android 端对齐：multipart 协议、进度回报节奏（500ms）、百分比取整规则、取消回调（errCode 9010007）、启动通知（uploadTime == 0 的 success 回调携带真实 uploadId）
• 分块失败时该并发 worker 停止领取新分块，其余在途分块传完后整体报失败（最终结果语义与 Android 一致）
• 已知限制：timeout 同时作为 HTTP 读超时，弱网下 1MB 分块可能触发超时（errCode 9010004），可按需调大 timeout 或调小 chunkSize

验证

• 鸿蒙模拟器（HarmonyOS 6.0.1）端到端实测通过：3MB/20MB 文件上传（1MB 分块、3 并发）、服务端合并文件 MD5 与源文件/应用内 cryptoFramework 计算值一致、启动通知契约、中途取消（9010007 + 服务端分片不合并）、服务端关停（9010003）、文件不存在（9010001）
• uni.chooseFile 在鸿蒙端返回 file://docs/storage/Users/currentUser/... 文件库 URI，实现已按 fs.openSync(uri) 方式支持

平台兼容性

uni-app(5.24)

uni-app x(5.24)

hens-upload-chunk 分块上传

用于 uni-app x App 的大文件分块上传插件，支持并发上传、进度回调、任务状态查询和取消任务。

兼容性

快速开始

import {
  startChunkUpload,
  cancelUpload,
  getUploadStatus,
  ChunkUploadOptions,
  UploadProgress,
  UploadResult,
  UploadFail,
  CancelUploadOptions,
  CancelUploadResult,
  GetUploadStatusOptions,
  UploadStatusResult
} from '@/uni_modules/hens-upload-chunk'

let currentUploadId = ''

const options : ChunkUploadOptions = {
  filePath: '/path/to/video.mp4',
  uploadUrl: 'https://example.com/upload',
  chunkSize: 1024 * 1024,
  maxConcurrency: 3,
  timeout: 30000,
  headers: {
    'Authorization': 'Bearer your-token'
  } as UTSJSONObject,
  formData: {
    'userId': '12345',
    'fileName': 'video.mp4'
  } as UTSJSONObject,
  : (progress : UploadProgress) => {
    console.log('上传进度: ' + progress.percentage.toString() + '%')
    console.log('上传速度: ' + progress.uploadSpeed.toString() + ' bytes/s')
  },
  success: (result : UploadResult) => {
    // uploadTime 为 0 时是任务创建通知，可在这里取得取消和查询所需的 uploadId。
    if (result.uploadTime == 0) {
      currentUploadId = result.uploadId
      return
    }

    console.log('上传完成: ' + result.uploadId)
  },
  fail: (error : UploadFail) => {
    console.log('上传失败: ' + error.errCode.toString() + ' ' + error.errMsg)
  },
  complete: (_ : any) => {
    console.log('上传任务结束')
  }
}

startChunkUpload(options)

headers 和 formData 请传普通对象并转换为 UTSJSONObject，不要传 Map。

取消上传

const options : CancelUploadOptions = {
  uploadId: currentUploadId,
  success: (result : CancelUploadResult) => {
    console.log('已取消: ' + result.uploadId)
  },
  fail: (error : UploadFail) => {
    console.log('取消失败: ' + error.errMsg)
  }
}

cancelUpload(options)

查询状态

const options : GetUploadStatusOptions = {
  uploadId: currentUploadId,
  success: (result : UploadStatusResult) => {
    console.log('状态: ' + result.status)
    console.log('进度: ' + result.progress.percentage.toString() + '%')
  },
  fail: (error : UploadFail) => {
    console.log('查询失败: ' + error.errMsg)
  }
}

getUploadStatus(options)

状态查询用于仍在运行的任务。任务成功、失败或取消后可能立即被清理，此时查询会返回“上传任务不存在”。

API

startChunkUpload(options)

开始上传，无返回值。任务创建成功和上传完成时会分别调用一次 success：

• 任务创建：uploadTime == 0、totalChunks == 0，此时保存 uploadId。
• 上传完成：uploadTime > 0，此时读取最终结果。

complete 只在上传最终成功或失败后调用，不会随任务创建通知调用。

ChunkUploadOptions

UploadProgress

UploadResult

cancelUpload(options)

使用任务创建通知返回的 uploadId 取消仍在运行的任务。成功结果包含：

getUploadStatus(options)

使用 uploadId 查询仍在运行的任务，返回 uploadId、status 和 progress。status 可能为：

pending、uploading、completed、failed、cancelled。

服务端协议

uploadUrl 必须接收 multipart/form-data POST 请求。插件会为每个分块发送以下字段：

formData 中的字段也会随每个分块发送。服务端对已接收的分块应返回任意 2xx 状态码，并在收齐同一 uploadId 的全部分块后按 chunkIndex 顺序合并。插件不会额外发送“合并完成”请求。

为适应并发请求和网络重试，建议服务端将 uploadId + chunkIndex 作为幂等键。不要依赖 multipart 中的分块文件名识别原文件；原文件名等业务信息请通过 formData 明确传递。

错误码

使用注意

• 业务应用负责选择文件并取得有效的本地路径；涉及相册、媒体或外部存储时，应在业务侧申请相应权限。
• 不要在 headers 中手动设置 Content-Type，multipart boundary 由插件生成。
• 生产环境建议使用 HTTPS。使用 HTTP 时，需要按目标平台配置明文网络访问策略。
• 应用进入后台后，上传可能受到系统调度或进程回收影响；当前版本不承诺后台持续上传。
• 弱网环境可减小 chunkSize、降低 maxConcurrency 并适当增大 timeout。