gt-shard-upload

高性能、支持极速并发的 Web 端文件分片上传 SDK。

gt-shard-upload 是一个基于 TypeScript 构建的现代化文件上传库。它专门处理大文件的分片上传、秒传、断点续传及进度展示，同时针对小文件会自动降级为极速单次直传。底层的 Web Worker 多线程架构让其在计算大文件 Hash 时丝毫不阻塞浏览器主线程。

✨ 特性

• 🚀 智能分片调度：自动以阈值（默认 10MB）区分大小文件，大文件分片，小文件直传。
• ⚡ 多线程 Hash：内置 Web Worker 拆片及 MD5 计算，不引起主线程卡顿。
• 🔄 完善的状态机：支持精准到单一文件维度的暂停 (Pause)、恢复 (Resume) 与取消 (Cancel)，任意文件进度互不沾染。
• 🛡️ 异常拦截自动重试：网络抖动引起的分片上传失败会自动进入受控排队重试，提供最稳固的底线重传机制。
• 📊 全息进度反馈：无论单文件还是多文件队列并发，皆支持输出总体及细致到各个子文件的百分比及分块进度报文。

📦 安装

使用 npm:

npm install gt-shard-upload

使用 pnpm:

pnpm install gt-shard-upload

🚀 快速上手

1. 实例化 SDK

在发起任何上传过程前，你需要传入配置实例化该类。

import GtUpload from "gt-shard-upload";

const uploader = new GtUpload({
  domain: "https://api.example.com", // 【必填】调用环境的域名(imagetest.gt.cn/image-lz.gt.cn)
  maxConcurrent: 3, // 【可选】最高几条并发传输，默认：2
  chunkSize: 5 * 1024 * 1024, // 【可选】文件分片大小，默认：5MB
  largeFileThreshold: 10 * 1024 * 1024, // 【可选】触发大文件分片机制的阈值，默认：10MB
});

2. 发起上传动作

为了安全考虑，上传组件在真正发送切片前，会向你索要对应的授权码凭证，因此在调用 .upload() 时，请传入你的取码异步回调。该组件同时兼容单个 File 或 File[] 数组。

// 假设这是通过输入框 <input type="file" multiple id="fileInput" /> 获取到的文件列表
const files = document.getElementById("fileInput").files;

uploader
  .upload(
    files,
    // 授权码获取拦截器（SDK 向你抛回当前文件的上下文要求鉴权）
    async (file, chunkInfo) => {
      // 调用你的项目后端 API 获取临时秘钥/上传授权
      const res = await fetch("/your-auth-api", {
        method: "POST",
        body: JSON.stringify(chunkInfo),
      });
      const data = await res.json();
      return data.authCode; // 务必返回供下游使用的凭证
    },
    // 进度回调事件
    (progress) => {
      console.log(`上传总计: ${progress.percent}%`);
      console.log(
        `完成块数: ${progress.uploadedChunks} / ${progress.totalChunks}`
      );

      // 多文件上传下，它还包含了所选的多组文件的单独立体进度
      if (progress.fileProgressList) {
        progress.fileProgressList.forEach((item) => {
          console.log(`${item.file.name}: ${item.percent}%`);
        });
      }
    }
  )
  .then((results) => {
    console.log("所有文件均已上传并处理完毕！", results);
  })
  .catch((error) => {
    console.error("任务彻底失败或已取消：", error);
  });

🎛️ 任务流转控制 API

SDK 从底层便支持对整个事件及独立文件的强干预机制。你可以只向以下方法传递特定的 file 对象来精准管理它，也可以通过不传参数来一次性管控目前所有的任务池。

暂停 (Pause)

临时冻结网络请求并且封存已上传的分块断点。

// 仅暂停特定文件的动作（specificFile 为当初选中的原生 File 实例对象，通常源自 input.files[i]）
uploader.pause(specificFile);

// 挂起当前 SDK 下处于任何步骤的全体文件
uploader.pause();

恢复 (Resume)

解冻断点继续上传。此举会自动为因过期而废弃小文件自动拉取新一轮鉴权凭证从而避免报错。

// 恢复特指对象的进度（specificFile 需与触发暂停时的 File 实例保持一致引用）
uploader.resume(specificFile);

// 唤起所有挂起的上传文件
uploader.resume();

取消 (Cancel)

彻底剪断连接生命线及阻断任何重试图谋。已上传的部分可能会成为垃圾碎片，但在前端侧其占用内存以及队列执行权会被尽数清空抹杀。

// 取消并销毁单独文件的排队与网络（specificFile 即原始选中的 input File 对象）
uploader.cancel(specificFile);

// 清空抛弃所有正在等待和传输中的所有数据池
uploader.cancel();

📄 许可

MIT © [gt-upload]