cloud-upload-hub：一款让多云存储上传变简单的神器 🚀

在前端项目中，我们经常需要上传静态资源到云存储，比如阿里云 OSS 、腾讯云 COS 。然而，每个平台的 API 规则不同，参数格式各异，导致开发者需要单独适配每个云服务，增加了不必要的重复工作。

有没有更简单 的方案？有的！今天向大家介绍 cloud-upload-hub，一款专为多云存储场景设计的轻量级上传工具，让你轻松搞定跨云存储文件上传！

什么是 cloud-upload-hub？

cloud-upload-hub 是一个轻量级的前端多云存储上传工具，支持阿里云 OSS、腾讯云 COS 等主流云存储服务，提供统一的 API 和灵活的配置方式，让文件上传变得更简单、更高效。

核心特性：

✅ 多云支持 ：兼容阿里云 OSS、腾讯云 COS，无需额外适配

✅ 简洁 API ：统一接口封装，免去不同平台的上传逻辑差异

✅ 灵活配置 ：支持 CLI 命令行和配置文件两种方式，适配不同场景

✅ 高可靠性 ：内置自动重试 机制，保证上传成功率

✅ 实时进度 ：支持进度监控 ，让上传状态一目了然

✅ 可扩展 ：提供自定义上传器支持，轻松拓展到其他存储服务

✅ 指定最后上传的文件 ：默认 index.html，通过最后一个生效文件，解决资源无序上传带来的页面资源加载失败。

如何快速上手？

安装 cloud-upload-hub 只需一行命令：

css 复制代码

npm install cloud-upload-hub --save-dev

1️⃣ 使用命令行上传文件

如果你只想快速上传文件，不想写任何代码，可以直接在命令行执行：

css 复制代码

cloud-upload-hub --source=dist --target=my-project --ossCredentials=./config/oss.conf.json

或者在package.json中：

json 复制代码

"scripts": {
    "uploader:test": cloud-upload-hub --source=dist --target=my-project --ossCredentials=./config/oss.conf.json
},

执行

bash 复制代码

npm run uploader:test

这行命令的作用是：

📁 source=dist ：指定本地待上传的文件夹

📤 target=my-project ：上传到云端的目标路径

🔑 ossCredentials=./config/oss.conf.json：使用本地的 OSS 配置文件进行身份验证

2️⃣ 使用配置文件管理上传

对于长期项目 ，或者需要频繁上传 的场景，推荐使用 uploader.config.js 配置文件来集中管理参数。

创建 uploader.config.js 文件，并填入以下内容：

javascript 复制代码

const defineConfig = ({ mode }) => {
  return {
      source: 'dist',
      target: 'my-cloud-storage',
      retryLimit: 5,  // 最多重试5次
      maxConcurrent: 10,  // 最大并发上传数
      lastFile: 'index.html',  // 指定最后上传的文件
      ossCredentials: './config/oss.conf.json',  // OSS 认证信息
      cosCredentials: async () => ({
        SecretId: 'your-secret-id',
        SecretKey: 'your-secret-key',
      }),
      onUploadSuccess(status) {
        console.log('✅ 上传成功:', status);
      },
      onUploadFail(status) {
        console.error('❌ 上传失败:', status);
      }
    };
};

module.exports = { defineConfig };

然后，只需运行：

js 复制代码

cloud-upload-hub --config=./uploader.config.js

即可自动完成上传！💡

云存储配置的多种方式

cloud-upload-hub 提供了三种方式来配置云存储认证信息：

1️⃣ 配置文件路径（适用于本地存储的 JSON 配置文件）

js 复制代码

ossCredentials: './config/oss.conf.json'

2️⃣ 直接在代码中写入配置对象

js 复制代码

ossCredentials: {
  bucket: 'my-bucket',
  accessKeyId: 'xxx',
  accessKeySecret: 'xxx',
  region: 'oss-cn-shanghai'
}

3️⃣ 使用异步函数动态获取凭据（适用于远程 API 获取认证信息）

js 复制代码

ossCredentials: async () => {
  const response = await fetch('your-api');
  return response.json();
}

支持自定义上传器

除了 OSS 和 COS，cloud-upload-hub 还支持自定义上传逻辑，让你可以接入其他云存储服务。

如何扩展自定义上传器？

在 uploader.config.js 中，添加 uploaderModules 参数：

js 复制代码

uploaderModules: [
  "./customUploader.js",
  async () => {
    // 这里可以动态加载你的上传逻辑
  }
]

然后，新建 customUploader.js 文件，编写你的上传逻辑：

js 复制代码

const { BaseUploader, registerUploader } = require('cloud-upload-hub');

class MyUploader extends BaseUploader {
  async uploadSingleFile(file, target) {
    // 你的自定义上传逻辑
    console.log(`Uploading ${file} to ${target}...`);
    return { success: true };
  }
}

registerUploader(MyUploader, {
  configName: 'myUploaderConfig',
  configRequiredFields: ['apiKey', 'storagePath'],
  type: 'customStorage'
});

这样，你的上传器就能无缝集成进 cloud-upload-hub 了！🎯

常见问题解答

1️⃣ 如何更改上传目标？

可以使用 mode 参数区分不同环境：

json 复制代码

"scripts": {
    "upload:prod": "cloud-upload-hub --mode=production"
}

然后在 uploader.config.js 里动态获取 target：

js 复制代码

const defineConfig = ({ mode }) => ({
  target: mode === 'production' ? 'oss/prod' : 'oss/dev',
});

export default defineConfig;

2️⃣ 如何监听上传成功/失败？

可以使用 onUploadSuccess 和 onUploadFail 处理事件：

js 复制代码

onUploadSuccess(status) {
  console.log('🚀 上传成功:', status);
},
onUploadFail(status) {
  console.error('🔥 上传失败:', status);
}

3️⃣ 上传日志是什么样的？

cloud-upload-hub 会输出清晰的上传日志：

json 复制代码

====== 共扫描了7个文件，开始上传资源文件。 ======

OSS资源文件，开始上传...

[OSS][SUCCESS][1/7]: src/.DS_Store -> test/sailing/src/.DS_Store
[OSS][SUCCESS][2/7]: src/upload/cosUpload.js -> test/sailing/src/upload/cosUpload.js
[OSS][SUCCESS][3/7]: src/main.js -> test/sailing/src/main.js
[OSS][SUCCESS][4/7]: src/upload/ossUpload.js -> test/sailing/src/upload/ossUpload.js
[OSS][SUCCESS][5/7]: src/utils/tasks.js -> test/sailing/src/utils/tasks.js
[OSS][SUCCESS][6/7]: src/utils/file.js -> test/sailing/src/utils/file.js

OSS资源文件，上传完成。

COS资源文件，开始上传...

[COS][SUCCESS][1/7]: src/main.js -> test/sailing/src/main.js
[COS][SUCCESS][2/7]: src/.DS_Store -> test/sailing/src/.DS_Store
[COS][SUCCESS][3/7]: src/upload/cosUpload.js -> test/sailing/src/upload/cosUpload.js
[COS][SUCCESS][4/7]: src/utils/tasks.js -> test/sailing/src/utils/tasks.js
[COS][SUCCESS][5/7]: src/utils/file.js -> test/sailing/src/utils/file.js
[COS][SUCCESS][6/7]: src/upload/ossUpload.js -> test/sailing/src/upload/ossUpload.js

COS资源文件，上传完成。

====== 开始上传生效文件。 ====== 

OSS生效文件，开始上传...

[OSS][SUCCESS][7/7]: src/index.html -> test/sailing/src/index.html

OSS生效文件，上传完成。

COS生效文件，开始上传...

[COS][SUCCESS][7/7]: src/index.html -> test/sailing/src/index.html

COS生效文件，上传完成。

====== 全部文件上传成功(7个) ======

总结

cloud-upload-hub 解决了多云存储上传的痛点，让文件上传变得更加高效、灵活。无论你是前端开发者、运维工程师，还是 DevOps 团队成员，都可以用它来轻松管理你的云存储资源。

📦 快速上手 ：npm install cloud-upload-hub --save-dev

🚀 立即体验 ：cloud-upload-hub --source=dist --target=my-project --ossCredentials=./config/oss.conf.json

让云存储上传变得更轻松、更高效 ，快来试试 cloud-upload-hub 吧！✨