evbee-s3-uploader

封装 AWS S3 文件上传功能的 JavaScript 工具包，支持简单上传、手动分片上传、并发控制与连接预热，主要面向浏览器环境。

安装

npm install evbee-s3-uploader

安装后无需任何额外配置，直接在项目中使用即可。所有依赖（包括 @aws-sdk/*）已打包进产物，零运行时依赖。

产物已包含浏览器所需的 Node.js polyfill（buffer、crypto、stream 等），兼容 webpack 4 / 5、Vite 等主流构建工具。 分片上传基于 S3Client 原生 API 手动实现，不依赖 @aws-sdk/lib-storage。

快速开始

import EvbeeS3Uploader from 'evbee-s3-uploader';

const uploader = new EvbeeS3Uploader({
  region: 'ap-east-1',
  credentials: {
    accessKeyId: 'YOUR_ACCESS_KEY',
    secretAccessKey: 'YOUR_SECRET_KEY',
  },
  bucket: 'my-bucket',
  keyPrefix: 'path/to/',
});

// 简单上传（建议 < 20MB）
const result = await uploader.simpleUpload({
  fileName: 'file.txt',
  Body: file,
});

// 分片上传（≥ 20MB，自动分片 + 并发）
const result = await uploader.multipartUpload({
  fileName: 'large-file.zip',
  Body: largeFile,
  warmUpConnectionCount: 6, // HTTP/1.1 下先预热 6 条连接
  onProgress: (progress) => {
    console.log(`上传进度: ${progress.percent}%`);
  },
});

API

new EvbeeS3Uploader(options)

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | region | string | 是 | AWS 区域 | | credentials.accessKeyId | string | 是 | Access Key ID | | credentials.secretAccessKey | string | 是 | Secret Access Key | | bucket | string | 否 | 默认 Bucket（单次调用可覆盖） | | keyPrefix | string | 否 | Key 路径前缀 |

simpleUpload(params)

简单上传，适用于小文件（建议 < 20MB）。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | fileName | string | 是 | 文件名（自动拼接 keyPrefix） | | Body | File|Blob|Uint8Array | 是 | 文件内容 | | bucket | string | 否 | 覆盖默认 Bucket | | onProgress | Function | 否 | 进度回调（仅在上传完成时触发一次 100%） | | extraParams | Object | 否 | 额外的 S3 参数 |

simpleUpload 底层使用 FetchHttpHandler（浏览器 fetch），fetch 不支持上传进度。进度回调仅在成功后触发 { loaded: 100, total: 100, percent: 100 }。

multipartUpload(params)

分片上传，适用于大文件。基于 S3Client 原生 API（CreateMultipartUpload → UploadPart → CompleteMultipartUpload）手动实现，采用滑动窗口并发池，支持连接预热。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | fileName | string | 是 | — | 文件名（自动拼接 keyPrefix） | | Body | File|Blob|Uint8Array | 是 | — | 文件内容 | | bucket | string | 否 | — | 覆盖默认 Bucket | | concurrency | number | 否 | 6 | 同时在传的分片数 | | partSize | number | 否 | 12MB | 分片大小（字节） | | warmUpConnectionCount | number | 否 | 0 | 上传前并发发送 HEAD 请求预热连接（HTTP/1.1 下建议设为 concurrency） | | onProgress | Function | 否 | — | 进度回调 ({ percent, uploadedBytes, totalBytes, currentPart, totalParts }) | | debug | boolean | 否 | false | 开启后在 console 输出每片上传耗时与速率 | | extraParams | Object | 否 | — | 额外的 S3 参数 |

分片自适应规则：分片数不超过 10000（S3 上限），单片不小于 5MB（S3 要求）。

abortUpload(params)

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | Bucket | string | 是 | S3 Bucket 名称 | | Key | string | 是 | 文件 Key | | UploadId | string | 是 | 上传 ID |

listUploads(params)

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | Bucket | string | 是 | S3 Bucket 名称 | | Prefix | string | 否 | Key 前缀过滤 |

getClient()

返回原生 S3Client 实例，用于高级操作。

所有方法返回统一结构

{ success: true, data: {} }   // 成功
{ success: false, error: '' } // 失败

License

ISC