chunk-uploader

一个轻量、高效的大文件分块上传工具，支持并发上传、断点续传校验、失败重试与进度监听，适用于浏览器端大文件（如视频、备份包等）

特性

• 分块上传：自动将大文件切分为固定大小的块并上传，降低单次请求负载。
• 并发控制：支持配置最大并发请求数，提升上传效率。
• 存在校验：上传前调用 checkUrl 校验分块是否已上传，支持断点续传。
• 失败重试：上传与校验请求支持自定义重试次数，增强网络容错能力。
• 实时进度：提供 onProgress 回调，返回上传百分比与字节级进度信息。
• 灵活配置：支持自定义上传、校验、合并接口地址，适配多种后端架构。

参数说明

默认文件哈希算法: SHA256

| 参数 | 类型 | 必填 | 说明 | | :----------------- | :------------------- | :--: | :----------------------------------------------------------------------------------------------------- | | baseUrl | string、string[] | ❌ | 服务器地址 | | uploadUrl | string、string[] | ❌ | 上传地址（默认上传地址：/api/file/upload, 请求参数: file、chunkIndex、startIndex、endIndex、hash） | | checkUrl | string、string[] | ❌ | 检查文件是否已经上传的接口地址：基于 GET 请求检查，默认使用 URL 参数：hash | | mergeUrl | string | ❌ | 合并文件接口地址：（默认参数：fileName、chunkHashList） | | file | File | ✅ | 用户选择的文件对象（来自 <input type="file">） | | chunkSize | number | ❌ | 每个分块大小（默认 5MB） | | uploadedChunks | UploadedChunk[] | ❌ | 已上传分片 | | maxConcurrency | number | ❌ | 并发上传请求数（默认 6） | | uploadRetryCount | number | ❌ | 分片上传失败重试次数（默认 3） | | checkRetryCount | number | ❌ | 分片校验请求失败重试次数（默认 3） | | onProgress | function | ❌ | 进度回调。函数入参： { uploaded, total, percent } | | uploadChunk | function | ❌ | 自定义分片文件上传函数（函数入参： { url, chunk }） | | checkChunk | function | ❌ | 自定义分片文件检测函数（函数入参： { url, hash }） | | mergeChunks | function | ❌ | 自定义分片文件合并函数 （函数入参：{url, fileName, chunks}） |

[!WARNING] 使用**uploadedChunks**参数时，请确保已上传的分片信息与实际分片信息一致，否则可能会导致文件损坏。

使用示例

1. 基础示例

• 调用默认上传路径上传分片
• 不会调用分片文件检查接口
• 不会调用分片文件合并接口

import { chunkUpload, ChunkUploadResponse } from '@tooltik/chunk-uploader';

chunkUpload({ file: file })
    .then((response: ChunkUploadResponse) => {
        console.log('上传成功', response);
    })
    .catch(error => {
        console.log('上传失败', error);
    });

2. 多子域上传

默认情况下，浏览器限制了同域下的并发请求数，因此，如果并发请求超过 6 个，会到导致上传效率低的问题。因此将上传地址设置为多个子域，提高上传速度。

uploadUrl、checkUrl 两个参数支持传入多个子域，函数内部会自动处理负载均衡。

import { chunkUpload, ChunkUploadResponse } from '@tooltik/chunk-uploader';

chunkUpload({
    baseUrl: ['http://127.0.0.1:9001', 'http://127.0.0.1:9002', 'http://127.0.0.1:9003'],
    uploadUrl: '/api/file/chunk/upload',
    file: file
})
    .then((response: ChunkUploadResponse) => {
        console.log('上传成功', response);
    })
    .catch(error => {
        console.log('上传失败', error);
    });

3. 完整配置

import { chunkUpload, ChunkUploadResponse } from '@tooltik/chunk-uploader';

chunkUpload({
    baseUrl: ['http://127.0.0.1:7001', 'http://127.0.0.1:7002', 'http://127.0.0.1:7003'],
    uploadUrl: ['/api/file/chunk/upload', 'http://127.0.0.1:7004/file/chunk/upload'],
    checkUrl: ['/api/file/chunk/check', 'http://127.0.0.1:7005/file/chunk/check'],
    mergeUrl: 'http://127.0.0.1:7006/api/file/chunk/merge',
    file: file,
    chunkSize: 1024 * 1024 * 5,
    uploadedChunks: [
        {
            chunkIndex: 2,
            startIndex: 10485760,
            endIndex: 15728640,
            hash: '91e1d87b44f50ced3792191de9c5fc8f7d33832cfefa969fe01315b86b0627d7'
        },
        {
            chunkIndex: 3,
            startIndex: 15728640,
            endIndex: 20971520,
            hash: 'e30774fc1cfc96c2152ae2e35425aa7b0efa6f7d0977b6687c459a5274d045f4'
        }
    ],
    maxConcurrency: 6,
    uploadRetryCount: 3,
    checkRetryCount: 3,
    onProgress: progress => {
        console.log(progress);
    },
    uploadChunk(url, chunk) {
        return Promise.resolve(true);
    },
    checkChunk(url, hash) {
        return Promise.resolve(true);
    },
    mergeChunks(url, fileName, chunks) {
        return Promise.resolve('resource-id');
    }
})
    .then((response: ChunkUploadResponse) => {
        console.log(chunks);
    })
    .catch(error => {
        console.error('上传失败', error);
    });

适用场景

• 大文件上传
• 视频、音频、备份包等媒体文件上传
• 断点续传需求场景
• 高并发、高可靠性的文件服务前端集成

changelist

• 0.0.3
  • 新增参数：uploadedChunks, 增强断点续传功能