CDN 上传工具集 (@zippybee/cdn-uploader)

介绍

@zippybee/cdn-uploader 是一个集成了三大云存储服务（阿里云OSS、七牛云、又拍云）的TypeScript工具库，提供统一的API接口用于文件上传、文件管理、目录管理等功能。

特性

• 🚀 支持三大主流云存储服务：阿里云OSS、七牛云、又拍云
• 📦 TypeScript 编写，提供完整的类型定义
• 🔧 统一的API接口，易于使用和切换
• 📁 支持单文件上传、批量上传、文件夹上传
• 🗂️ 提供文件管理功能：列表、删除、版本管理
• ⚡ 支持并发上传，提高上传效率
• 🎯 自动检测文件MIME类型（阿里云OSS）

安装依赖

npm i @zippybee/cdn-uploader
# 或
pnpm add @zippybee/cdn-uploader
# 或
yarn add @zippybee/cdn-uploader

快速开始

引入模块

import { AliOssUploader, QiniuUploader, UpyunUploader } from '@zippybee/cdn-uploader';

阿里云OSS (AliOssUploader)

初始化

import { AliOssUploader } from '@zippybee/cdn-uploader';

const aliUploader = new AliOssUploader({
  region: 'oss-cn-hangzhou', // 阿里云OSS区域
  accessKeyId: '你的AccessKeyId', // 阿里云OSS AccessKeyId
  accessKeySecret: '你的AccessKeySecret', // 阿里云OSS AccessKeySecret
  bucket: '你的存储桶名称', // 阿里云OSS存储空间名称
  endpoint: '你的自定义域名', // 可选：阿里云OSS访问域名
  bucketPath: '/path/to/bucket', // 可选：存储空间路径
});

配置参数说明

| 参数 | 类型 | 必需 | 说明 | | --------------- | ------ | ---- | ------------------------- | | region | string | 是 | 阿里云OSS区域 | | accessKeyId | string | 是 | 阿里云OSS AccessKeyId | | accessKeySecret | string | 是 | 阿里云OSS AccessKeySecret | | bucket | string | 是 | 阿里云OSS存储空间名称 | | endpoint | string | 否 | 阿里云OSS访问域名 | | bucketPath | string | 否 | 存储空间路径 |

API 方法

uploadFile - 上传文件

const result = await aliUploader.uploadFile(
  '/path/to/local/file.jpg', // 本地文件路径
  'remote/path/file.jpg', // 存储桶路径
  {
    // 可选参数
    headers: {
      'Cache-Control': 'max-age=31536000',
    },
  },
);
console.log('上传成功:', result.url);

uploadStream - 流式上传

import { createReadStream } from 'fs';

const stream = createReadStream('/path/to/file.jpg');
const result = await aliUploader.uploadStream(stream, 'remote/path/file.jpg', {
  headers: {
    'Content-Type': 'image/jpeg',
  },
});

listFiles - 获取文件列表

const result = await aliUploader.listFiles({
  prefix: 'images/', // 文件前缀
  'max-keys': '100', // 最大返回数量
});
console.log('文件列表:', result.items);
console.log('下一页标记:', result.nextContinuationToken);

deleteFolder - 删除文件夹

const result = await aliUploader.deleteFolder('images/folder/');
console.log(`删除了 ${result.deleteCount} 个文件`);

keepLatestFolders - 保留最新文件夹

// 保留最新的3个版本文件夹，删除其他旧版本
await aliUploader.keepLatestFolders('releases/', 3);

uploadFolder - 上传文件夹

const result = await aliUploader.uploadFolder(
  './dist', // 本地文件夹路径
  '/website/v1.0.0/', // 远程存储路径
  {
    limit: 10, // 并发上传数量限制
    exclude: ['*.tmp', '*.log'], // 排除的文件模式
    uploadOptions: {
      // 上传选项
      headers: {
        'Cache-Control': 'max-age=31536000',
      },
    },
  },
);
console.log(`上传完成，共 ${result.uploadCount} 个文件`);

七牛云 (QiniuUploader)

初始化

import { QiniuUploader } from '@zippybee/cdn-uploader';

const qiniuUploader = new QiniuUploader({
  accessKey: '你的七牛AccessKey',
  secretKey: '你的七牛SecretKey',
  bucket: '你的存储桶名称',
  cdn_url: '你的CDN地址', // 可选
  expires: 7200, // Token过期时间，单位秒，默认7200
  useCdnDomain: true, // 可选：是否使用CDN域名
  useHttpsDomain: true, // 可选：是否使用HTTPS域名
});

配置参数说明

| 参数 | 类型 | 必需 | 说明 | | -------------- | ------- | ---- | ------------------------------- | | accessKey | string | 是 | 七牛云Access Key | | secretKey | string | 是 | 七牛云Secret Key | | bucket | string | 是 | 存储桶名称 | | cdn_url | string | 否 | CDN地址 | | expires | number | 否 | Token过期时间，单位秒，默认7200 | | useCdnDomain | boolean | 否 | 是否使用CDN域名 | | useHttpsDomain | boolean | 否 | 是否使用HTTPS域名 |

API 方法

uploadFile - 上传文件

const result = await qiniuUploader.uploadFile(
  './local/file.jpg', // 本地文件路径
  'remote/path/file.jpg', // 远程存储路径
  {
    isCover: true, // 是否覆盖同名文件
    base_root: './local', // 本地根路径
    is_steam: false, // 是否使用流式上传
  },
);
console.log('上传成功:', result);

listFiles - 列出文件

const files = await qiniuUploader.listFiles({
  remote_dir: 'images/', // 远程目录路径
  marker: '', // 分页标记
  limit: 100, // 每次获取的最大数量
  delimiter: '/', // 分隔符
});
console.log('文件列表:', files);

deleteFolder - 删除文件夹

await qiniuUploader.deleteFolder('images/old-folder/');
console.log('文件夹删除成功');

uploadFolder - 上传文件夹

await qiniuUploader.uploadFolder(
  './dist', // 本地文件夹路径
  'website/v1.0.0/', // 远程存储路径
  ['*.tmp', '*.log'], // 排除的文件模式
  5, // 并发上传数量限制
);

setFileLifeCycle - 设置文件生命周期

const success = await qiniuUploader.setFileLifeCycle(
  'path/to/file.jpg', // 文件路径
  30, // 生命周期天数
);

又拍云 (UpyunUploader)

初始化

import { UpyunUploader } from '@zippybee/cdn-uploader';

const upyunUploader = new UpyunUploader({
  serverName: '你的服务名称', // 又拍云服务名称
  operatorName: '你的操作员名称', // 又拍云操作员名称
  password: '你的操作员密码', // 又拍云操作员密码
  cdn_url: '你的CDN域名', // 可选：CDN域名
});

配置参数说明

| 参数 | 类型 | 必需 | 说明 | | ------------ | ------ | ---- | ---------------- | | serverName | string | 是 | 又拍云服务名称 | | operatorName | string | 是 | 又拍云操作员名称 | | password | string | 是 | 又拍云操作员密码 | | cdn_url | string | 否 | CDN域名 |

API 方法

uploadFile - 上传文件

const result = await upyunUploader.uploadFile(
  './local/file.jpg', // 本地文件路径
  '/remote/path/', // 远程存储路径
);
console.log('上传结果:', result);

listFiles - 获取文件列表

const files = await upyunUploader.listFiles('/images/');
console.log('文件列表:', files);

listFolders - 获取文件夹列表

const folders = await upyunUploader.listFolders('/');
console.log('文件夹列表:', folders);

deleteFolderAndFiles - 删除文件夹及其内容

await upyunUploader.deleteFolderAndFiles('/old-folder/');
console.log('文件夹删除成功');

uploadFolder - 上传文件夹

const result = await upyunUploader.uploadFolder(
  './dist', // 本地文件夹路径
  '/website/', // 远程存储路径
  ['*.tmp', '*.log'], // 排除的文件模式
);
console.log(`上传完成，共 ${result.total_files_uploaded} 个文件`);

deleteVersionFolder - 删除版本文件夹

const result = await upyunUploader.deleteVersionFolder(
  '1.0.5', // 当前版本号
  '/releases/', // 远程路径
  2, // 保留的版本数量
);
console.log('版本清理结果:', result);

使用示例

完整上传示例

import { AliOssUploader, QiniuUploader, UpyunUploader } from '@zippybee/cdn-uploader';

// 阿里云OSS上传示例
const aliUploader = new AliOssUploader({
  region: 'oss-cn-hangzhou',
  accessKeyId: 'your-access-key-id',
  accessKeySecret: 'your-access-key-secret',
  bucket: 'your-bucket-name',
});

async function uploadToAli() {
  try {
    const result = await aliUploader.uploadFile('./dist/index.html', 'website/index.html');
    console.log('阿里云上传成功:', result.url);
  } catch (error) {
    console.error('阿里云上传失败:', error);
  }
}

// 七牛云上传示例
const qiniuUploader = new QiniuUploader({
  accessKey: 'your-access-key',
  secretKey: 'your-secret-key',
  bucket: 'your-bucket-name',
  cdn_url: 'https://your-cdn-domain.com',
});

async function uploadToQiniu() {
  try {
    const result = await qiniuUploader.uploadFile('./dist/index.html', 'website/index.html');
    console.log('七牛云上传成功:', result.url);
  } catch (error) {
    console.error('七牛云上传失败:', error);
  }
}

// 又拍云上传示例
const upyunUploader = new UpyunUploader({
  serverName: 'your-server-name',
  operatorName: 'your-operator-name',
  password: 'your-password',
  cdn_url: 'https://your-cdn-domain.com',
});

async function uploadToUpyun() {
  try {
    const result = await upyunUploader.uploadFile('./dist/index.html', '/website/');
    console.log('又拍云上传成功:', result.url);
  } catch (error) {
    console.error('又拍云上传失败:', error);
  }
}

批量上传示例

async function batchUpload() {
  // 使用阿里云OSS批量上传文件夹
  const result = await aliUploader.uploadFolder('./dist', '/website/v1.0.0/', {
    limit: 10,
    exclude: ['*.map', '*.tmp'],
    uploadOptions: {
      headers: {
        'Cache-Control': 'max-age=31536000',
      },
    },
  });

  console.log(`批量上传完成: ${result.uploadCount}/${result.fileContent} 个文件`);
}

2 |不加密中转 |28020 |47.79.33.68:28020

类型定义

阿里云OSS类型

interface AliOssUploadOption {
  region: string;
  accessKeyId: string;
  accessKeySecret: string;
  bucket: string;
  endpoint?: string;
  bucketPath?: string;
}

interface AliUploadFolderOption {
  limit?: number;
  exclude?: string[];
  uploadOptions?: OSS.PutObjectOptions;
}

七牛云类型

interface QiniuUploadOption {
  accessKey: string;
  secretKey: string;
  bucket: string;
  expires?: number;
  useCdnDomain?: boolean;
  useHttpsDomain?: boolean;
  cdn_url?: string;
}

interface UploadFileOption {
  isCover?: boolean;
  base_root?: string;
  is_steam?: boolean;
  qiniuConfig?: qiniu.conf.Config;
}

又拍云类型

interface UpYunOptions {
  serverName: string;
  operatorName: string;
  password: string;
  cdn_url?: string;
}

interface UpYunFileRow {
  name: string;
  type: string;
  size: number;
  last_modified: number;
  length?: number;
  etag?: string;
}

更新日志

v1.0.14

• 🚀 新增阿里云OSS自动MIME类型检测
• 🔧 优化上传性能和错误处理
• 📝 完善文档和类型定义

v1.0.13

• 🐛 修复文件路径处理问题
• ⚡ 提升并发上传稳定性

许可证

ISC

贡献

欢迎提交 Issue 和 Pull Request！

支持

如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！