更新记录

1.0（2026-09-16）

1.0 基于 uni-app（Vue 3）的文件分片上传组件，支持图片/视频选择、并发分片上传、进度展示、失败重试

平台兼容性

uni-app(5.24)

chunk-upload 分片上传组件使用说明

基于 uni-app（Vue 3）的文件分片上传组件，支持图片/视频选择、并发分片上传、进度展示、失败重试，符合 easycom 规范（components/chunk-upload/chunk-upload.vue），无需手动注册即可在页面中直接使用。

一、快速开始

<template>
    <view class="page">
        <chunk-upload
            chunk-url="https://api.example.com/upload/chunk"
            merge-url="https://api.example.com/upload/merge"
            :limit="5"
            :chunk-size="4 * 1024 * 1024"
            :media-type="['image', 'video']"
            :header="{ Authorization: 'Bearer xxx' }"
            @success="onSuccess"
            @fail="onFail"
        />
    </view>
</template>

<script>
    export default {
        methods: {
            onSuccess({ file, url }) {
                console.log('上传成功：', file.name, url);
            },
            onFail({ file, msg }) {
                console.log('上传失败：', file.name, msg);
            }
        }
    };
</script>

项目启用 easycom 时（uni-app 默认开启），组件放在 components/chunk-upload/chunk-upload.vue 即可自动注册；未启用时需手动 import 并注册。

二、Props

mediaType 分派逻辑：

• 仅 image：调用 uni.chooseImage
• 仅 video：调用 uni.chooseVideo
• 混合：优先 uni.chooseMedia，不支持时降级 uni.chooseFile

三、Events

四、插槽

<chunk-upload chunk-url="..." merge-url="...">
    <view class="my-btn">选择文件并上传</view>
    <!-- 也可使用 <template #trigger> 包裹 -->
</chunk-upload>

五、上传流程

1. 选择文件（按 mediaType 分派选择 API，保留 size、文件名）。
2. 计算分片数：Math.ceil(file.size / chunkSize)，size 为 0 时按 1 片。
3. 并发上传分片（最多 3 个并发），每完成一片更新进度条。
4. 全部分片成功后调用合并接口，状态流转：

等待上传(pending) → 上传中(uploading) → 合并中(merging) → 上传成功(success)
                                                    ↘ 上传失败(fail) → 可重试/删除

六、后端接口约定

1. 分片接口 chunkUrl

• 请求方式：POST（multipart/form-data）
• 请求字段：

• 响应：JSON，status === 1 表示成功，例如 { "status": 1, "message": "ok" }

2. 合并接口 mergeUrl

• 请求方式：POST（application/json）
• 请求体：{ "fileId": "xxx", "fileName": "xxx.jpg", "totalChunks": 3 }
• 响应：JSON，status === 1 表示成功并返回最终地址：

{ "status": 1, "url": "https://cdn.example.com/files/xxx.jpg" }

若后端返回格式不是 status === 1，需调整组件中 uploadSingleChunk 与 mergeFile 的响应判断。

七、注意事项

1. 当前为"逻辑分片"实现：每个分片请求实际上传的是整个文件（filePath 相同），靠 chunkIndex/totalChunks 标识分片语义。生产环境中：
   • H5 端建议基于 Web File API（File.slice）实现真分片；
   • 小程序/App 端需 FileSystemManager 分段读取或接入原生插件。
2. Vue 3 响应式：组件内部已通过 this.fileList 中的代理对象进行状态更新，请勿在外部持有原始对象直接改写，否则视图不会更新。
3. 进度条按"成功分片数 / 总分片数"计算，合并阶段进度恒为 100%。
4. 失败重试会重置分片并重新走完整上传流程；删除仅移除列表项，如需清理后端临时分片请在 fail/删除逻辑中自行调用后端接口。
5. 视频选择受平台限制（如 chooseVideo 一次只能选一个）；混合选择的 count 参数在 chooseMedia 下可能不生效（微信端使用 maxCount）。
6. 分片大小建议结合后端限制（如 nginx client_max_body_size）调整，默认 2MB。