🚀 @chao_yan/bigfileuploader

一个支持 分片上传、大文件断点续传、并发控制、MD5 校验 的前端上传 SDK。
使用 TypeScript 编写，轻量、易扩展，适合二次封装到任意上传业务中。

✨ 特性

• ⚡ 分片上传：自动将大文件切割为小块上传
• 🧩 并发控制：限制同时上传的请求数量，防止卡顿
• 🧠 断点续传：支持中断后从已完成分片继续
• 🔐 MD5 校验：计算文件唯一标识，用于秒传与分片校验
• 🪶 轻量可扩展：无第三方 UI 依赖，可灵活集成到任意项目
• 📦 TypeScript 支持：完整类型定义与开发体验

📦 安装

npm install @chao_yan/bigfileuploader
# 或使用 yarn
yarn add @chao_yan/bigfileuploader

📝 使用

import { FileUploader } from '@chao_yan/bigfileuploader'

const file = document.querySelector('input[type="file"]').files[0]
const uploader = new FileUploader(file, {
  url: 'http://localhost:3000/upload',
  chunkSize: 1024 * 1024 * 5, // 分片大小
  concurrent: 3, // 并发数
  retry: 3, // 重试次数

  // 上传前钩子
  beforeUpload: (file) => {
      
  }

📖 API

FileUploader

构造函数

constructor(file: File, options: FileUploaderOptions)

方法

start(): Promise<void> // 开始上传
pause(): void // 暂停上传
on(event: string, callback: Function): void // 监听事件

事件

on('start', callback: Function) // 上传开始
on('progress', callback: Function) // 上传进度
on('success', callback: Function) // 上传成功
on('error', callback: Function) // 上传失败
on('complete', callback: Function) // 上传完成

配置项

interface FileUploaderOptions {
  url: string // 上传接口地址
  chunkSize: number // 分片大小
  concurrent: number // 并发数
  retry: number // 重试次数
  beforeUpload?: (file: File) => void // 上传前钩子
  afterUpload?: (file: File) => void // 上传后钩子
}

目录结构

file-upload-sdk/ ├── src/ │ ├── index.ts // 导出入口 │ ├── uploader.ts // 主类 FileUploader │ ├── utils/ │ │ ├── chunk.ts // 分片工具 │ │ ├── hash.ts // 文件hash │ │ ├── retry.ts // 重试机制 │ │ └── request.ts // 并发控制 ├── example/ │ └── demo.html // 测试页面 ├── package.json ├── tsconfig.json └── README.md

🧾 License | 开源许可

本项目基于 MIT License 开源许可协议发布。

Copyright (c) 2025 chao_yan

本软件及其文档可免费使用、复制、修改、合并、发布和分发，
前提是必须在所有副本中保留上述版权声明和本许可说明。

本软件按 “原样” 提供，作者 不承担任何责任或保证。
使用者应自行承担因使用本软件所产生的风险。

📘 English Version

This project is licensed under the MIT License.

Copyright (c) 2025 chao_yan

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

📄 查看完整许可证 →