npm - @be-link/cos - Versions diffs - 1.11.4 → 1.12.0-beta.0 - Mend

@be-link/cos 1.11.4 → 1.12.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/README.md CHANGED Viewed

@@ -1,11 +1,426 @@
-# `cos`
+# @be-link/cos
-> TODO: description
+腾讯云 COS 浏览器端文件上传工具。
-## Usage
+## 功能特性
+- 🌐 **浏览器端上传** - 单文件上传，支持进度回调
+- 🔐 **安全可靠** - 自动获取临时密钥，无需暴露永久密钥
+- ⚡ **性能优化** - 大文件 MD5 分片计算，避免内存溢出
+- 📝 **TypeScript** - 完整的类型定义支持
+- 🎯 **多环境** - 支持开发、测试、生产环境配置
+- 🔧 **安全设计** - mode 必填无默认值，强制显式配置，避免环境配置错误
+---
+## 安装
+```bash
+npm install @be-link/cos cos-js-sdk-v5 crypto-js
+```
+---
+## 快速开始
+### Vue 项目
+**方式一：立即初始化**
+```vue
+<template>
+  <div>
+    <input type="file" @change="handleFileChange" />
+    <button @click="handleUpload" :disabled="uploading">
+      {{ uploading ? `上传中 ${progress}%` : '上传文件' }}
+    </button>
+  </div>
+</template>
+<script setup>
+import { ref } from 'vue';
+import { BeLinkCOS } from '@be-link/cos';
+const file = ref(null);
+const uploading = ref(false);
+const progress = ref(0);
+// 创建上传器实例（mode 必填）
+const uploader = new BeLinkCOS({ mode: 'production' });
+const handleFileChange = (e) => {
+  file.value = e.target.files[0];
+};
+const handleUpload = async () => {
+  if (!file.value) return;
+  uploading.value = true;
+  try {
+    const result = await uploader.uploadFile(file.value, {
+      onProgressCallback: (data) => {
+        progress.value = Math.round(data.percent * 100);
+      },
+    });
+    console.log('上传成功:', result.url);
+  } catch (error) {
+    console.error('上传失败:', error);
+  } finally {
+    uploading.value = false;
+  }
+};
+</script>
+```
+**方式二：延迟初始化（支持异步配置）**
+```vue
+<script setup>
+import { ref, onMounted } from 'vue';
+import { BeLinkCOS } from '@be-link/cos';
+const uploader = new BeLinkCOS(); // 先创建实例
+onMounted(async () => {
+  // 从服务器获取配置
+  const config = await fetchConfigFromServer();
+  uploader.init({ mode: config.mode }); // 稍后初始化
+});
+const handleUpload = async () => {
+  const result = await uploader.uploadFile(file.value);
+  console.log('上传成功:', result.url);
+};
+</script>
+```
+### React 项目
+```jsx
+import { useState } from 'react';
+import { BeLinkCOS } from '@be-link/cos';
+// 创建上传器实例（mode 必填）
+const uploader = new BeLinkCOS({ mode: 'production' });
+function FileUploader() {
+  const [file, setFile] = useState(null);
+  const [uploading, setUploading] = useState(false);
+  const [progress, setProgress] = useState(0);
+  const handleUpload = async () => {
+    if (!file) return;
+    setUploading(true);
+    try {
+      const result = await uploader.uploadFile(file, {
+        onProgressCallback: (data) => setProgress(Math.round(data.percent * 100)),
+      });
+      console.log('上传成功:', result.url);
+    } catch (error) {
+      console.error('上传失败:', error);
+    } finally {
+      setUploading(false);
+    }
+  };
+  return (
+    <div>
+      <input type='file' onChange={(e) => setFile(e.target.files[0])} />
+      <button onClick={handleUpload} disabled={uploading}>
+        {uploading ? `上传中 ${progress}%` : '上传文件'}
+      </button>
+    </div>
+  );
+}
+```
+### 原生 JS
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <script type="module">
+      import { BeLinkCOS } from '@be-link/cos';
+      // 创建上传器实例（mode 必填）
+      const uploader = new BeLinkCOS({ mode: 'production' });
+      // 上传
+      document.getElementById('upload').onclick = async () => {
+        const file = document.getElementById('file').files[0];
+        const result = await uploader.uploadFile(file, {
+          onProgressCallback: (data) => {
+            console.log('进度:', data.percent * 100 + '%');
+          },
+        });
+        console.log('上传成功:', result.url);
+      };
+    </script>
+  </head>
+  <body>
+    <input type="file" id="file" />
+    <button id="upload">上传</button>
+  </body>
+</html>
 ```
-const cos = require('cos');
-// TODO: DEMONSTRATE API
+---
+## 多环境上传
+支持同时上传到不同环境：
+```typescript
+import { BeLinkCOS } from '@be-link/cos';
+// 创建开发环境上传器
+const devUploader = new BeLinkCOS({ mode: 'development' });
+// 创建生产环境上传器
+const prodUploader = new BeLinkCOS({ mode: 'production' });
+// 同时上传到不同环境
+await Promise.all([devUploader.uploadFile(file), prodUploader.uploadFile(file)]);
+```
+---
+## API 文档
+### `new BeLinkCOS(config?)`
+创建 COS 上传器实例
+**支持两种使用方式：**
+1. **立即初始化**：传入配置对象，构造函数中自动调用 `init()`
+2. **延迟初始化**：不传配置，稍后调用 `init()` 方法（支持异步配置）
+**参数：**
+- `config.mode` - **必填** 环境模式：`'development'` | `'testing'` | `'production'`
+- `config.headers` - 可选，自定义请求头
+- `config.ScopeLimit` - 可选，是否限制临时密钥范围（默认 `false`）
+- `config.debug` - 可选，是否开启调试模式（默认 `false`）
+**示例：**
+```typescript
+// 方式一：立即初始化
+const uploader = new BeLinkCOS({ mode: 'production' });
+// 方式二：延迟初始化（支持异步配置）
+const uploader = new BeLinkCOS();
+const config = await fetchConfig(); // 从服务器获取配置
+uploader.init({ mode: config.mode });
+// 带自定义请求头
+const uploader = new BeLinkCOS({
+  mode: 'production',
+  headers: { 'x-custom': 'value' },
+  debug: true, // 开启调试日志
+});
+```
+### `uploader.init(config)`
+初始化 COS 实例（用于延迟初始化场景）
+**参数：**
+- `config.mode` - **必填** 环境模式
+- `config.headers` - 可选，自定义请求头
+- `config.ScopeLimit` - 可选，是否限制临时密钥范围
+- `config.debug` - 可选，是否开启调试模式
+**示例：**
+```typescript
+const uploader = new BeLinkCOS();
+uploader.init({ mode: 'production' });
+```
+### `uploader.uploadFile(file, config)`
+上传文件到 COS
+**参数：**
+- `file` - 要上传的文件对象
+- `config.onProgressCallback` - 可选，进度回调函数
+- `config.Headers` - 可选，自定义请求头
+**返回：**
+```typescript
+{
+  url: string,        // 文件访问 URL
+  Location: string,   // 文件位置
+  ETag: string,       // 文件 ETag
+  statusCode: number, // HTTP 状态码
+  headers: {}         // 响应头
+}
 ```
+**示例：**
+```typescript
+const result = await uploader.uploadFile(file, {
+  onProgressCallback: (data) => {
+    console.log('进度:', data.percent * 100 + '%');
+  },
+});
+console.log('上传成功:', result.url);
+```
+### `uploader.getSourceUrl(file)`
+获取文件上传后的 URL（不执行实际上传）
+```typescript
+const url = await uploader.getSourceUrl(file);
+```
+### `uploader.createFileMd5(file, chunkSize?)`
+计算文件 MD5 哈希值
+```typescript
+const md5 = await uploader.createFileMd5(file, 2 * 1024 * 1024); // 默认 2MB 分片
+```
+### `uploader.getConfig()`
+获取当前实例的配置信息
+```typescript
+const config = uploader.getConfig();
+console.log(config); // { mode: 'production', headers: {}, scopeLimit: false }
+```
+### `uploader.destroy()`
+销毁实例，清理资源
+```typescript
+uploader.destroy();
+```
+---
+## 环境配置
+| 环境        | Bucket             | 区域       |
+| ----------- | ------------------ | ---------- |
+| development | dev-1304510571     | ap-nanjing |
+| testing     | dev-1304510571     | ap-nanjing |
+| production  | release-1304510571 | ap-nanjing |
+---
+## TypeScript 类型
+```typescript
+import { BeLinkCOS } from '@be-link/cos';
+import type {
+  EnvMode, // 'development' | 'testing' | 'production'
+  BucketConfig, // Bucket 配置
+  InitConfig, // 初始化配置
+  UploadConfig, // 上传配置
+  UploadResult, // 上传结果
+} from '@be-link/cos';
+```
+---
+## 常见问题
+### 1. 两种初始化方式有什么区别？
+**立即初始化**：配置在编译时已知，直接传入构造函数
+```typescript
+const uploader = new BeLinkCOS({ mode: 'production' });
+```
+**延迟初始化**：配置需要异步获取（如从服务器获取），先创建实例再初始化
+```typescript
+const uploader = new BeLinkCOS();
+// 稍后（可以是异步）
+const config = await fetchConfigFromServer();
+uploader.init({ mode: config.mode });
+```
+**设计理念：** 参考了 `BeLinkLogDot` 的设计模式，支持更灵活的配置方式。
+### 2. 为什么 mode 必须传？
+**设计理念：强制显式配置，避免默认值陷阱**
+如果提供默认值（如 `development`），很容易出现以下问题：
+- 开发者忘记修改配置，生产环境代码误传到开发环境
+- 或者开发环境配置被复制到生产，导致测试数据污染生产环境
+**因此，我们要求必须显式指定环境：**
+```typescript
+// ✅ 正确：明确指定环境，不会搞错
+const uploader = new BeLinkCOS({ mode: 'production' });
+// ✅ 也可以延迟初始化
+const uploader = new BeLinkCOS();
+uploader.init({ mode: 'production' });
+```
+这样设计更安全，用户必须思考"我要上传到哪个环境"。
+### 3. 上传失败怎么办？
+检查：
+- `mode` 参数是否正确
+- 实例是否已初始化（调用了 `init()` 或构造函数传入了配置）
+- 网络是否正常
+- 浏览器控制台是否有错误信息（可以开启 `debug: true` 查看详细日志）
+### 4. 文件存储路径是什么？
+文件会自动存储到：`/beLinkAllSource/static/{文件类型}/{文件名}_{时间戳}.{扩展名}`
+例如：`/beLinkAllSource/static/image/avatar_1699999999999.png`
+### 5. 支持哪些文件类型？
+支持所有文件类型，会根据文件的 MIME 类型自动分类存储（image、video、audio、application、text、other）。
+### 6. 如何切换环境？
+创建不同环境的实例：
+```typescript
+const devUploader = new BeLinkCOS({ mode: 'development' });
+const prodUploader = new BeLinkCOS({ mode: 'production' });
+```
+---
+## 安全说明
+✅ 本工具使用**临时密钥**方式，通过云函数动态获取授权
+✅ 不会在客户端暴露永久密钥，安全可靠
+✅ 临时密钥具有时效性，过期自动失效
+---
+## 许可证
+ISC
+## 维护者
+zhuifeng <yangyiboys@163.com>

package/dist/beLinkCos.d.ts CHANGED Viewed

@@ -1,2 +1,162 @@
-declare const beLinkCOS: any;
-export default beLinkCOS;
+import { type EnvMode } from './config';
+import type { InitConfig, UploadConfig, UploadResult } from './types';
+/**
+ * BeLinkCOS 类 - 腾讯云 COS 文件上传工具
+ *
+ * 功能：文件上传、MD5 计算、临时密钥授权
+ *
+ * @example
+ * import { BeLinkCOS } from '@be-link/cos';
+ *
+ * // 方式一：构造函数传入配置，立即初始化
+ * const uploader = new BeLinkCOS({ mode: 'production' });
+ * await uploader.uploadFile(file);
+ *
+ * // 方式二：先创建实例，稍后初始化（支持异步配置）
+ * const uploader = new BeLinkCOS();
+ * const config = await fetchConfig(); // 从服务器获取配置
+ * uploader.init({ mode: 'production' });
+ * await uploader.uploadFile(file);
+ */
+export declare class BeLinkCOS {
+    /** COS SDK 实例 */
+    private cos;
+    /** COS 存储的基础路径 */
+    private readonly basePath;
+    /** 自定义请求头 */
+    headers: Record<string, any>;
+    /** 当前环境模式 */
+    mode: EnvMode | null;
+    /** 是否限制临时密钥的使用范围 */
+    private scopeLimit;
+    /** 生命周期状态 */
+    protected isInitialized: boolean;
+    protected isDestroyed: boolean;
+    /** 调试模式 */
+    private debug;
+    /**
+     * 构造函数
+     *
+     * 支持两种使用方式：
+     * 1. 立即初始化：传入配置对象，构造函数中自动调用 init()
+     * 2. 延迟初始化：不传配置，稍后调用 init() 方法（支持异步配置）
+     *
+     * @param config - 可选的初始化配置
+     * @param config.mode - **必填** 环境模式：'development' | 'testing' | 'production'
+     * @param config.headers - 可选，自定义请求头
+     * @param config.ScopeLimit - 可选，是否限制临时密钥的使用范围（默认 false）
+     * @param config.debug - 可选，是否开启调试模式（默认 false）
+     *
+     * @example
+     * // 立即初始化
+     * const uploader = new BeLinkCOS({ mode: 'production' });
+     *
+     * // 延迟初始化
+     * const uploader = new BeLinkCOS();
+     * // ... 稍后调用 uploader.init(config);
+     */
+    constructor(config?: InitConfig);
+    /**
+     * 初始化 COS 实例
+     * @param config 配置对象
+     * @description 可以在创建实例时通过构造函数传入配置，也可以稍后调用此方法初始化
+     */
+    init(config: InitConfig): void;
+    /**
+     * 初始化 COS SDK 实例
+     *
+     * 内部方法，通过云函数获取临时密钥
+     * 首次上传时会自动调用
+     *
+     * @returns Promise<void>
+     */
+    private initCOS;
+    /**
+     * 检查实例状态
+     */
+    protected checkState(methodName: string): boolean;
+    /**
+     * 内部日志方法
+     */
+    protected log(...args: unknown[]): void;
+    protected warn(...args: unknown[]): void;
+    protected error(...args: unknown[]): void;
+    /**
+     * 验证配置
+     */
+    protected validateConfig(config: InitConfig): boolean;
+    /**
+     * 获取配置
+     */
+    getConfig(): {
+        mode: EnvMode | null;
+        headers: Record<string, any>;
+        scopeLimit: boolean;
+    } | null;
+    /**
+     * 计算文件的 MD5 哈希值
+     *
+     * 性能优化：
+     * - 小文件（< 10MB）：一次性读取，速度更快
+     * - 大文件：分片读取，避免内存溢出
+     *
+     * @param file - 要计算 MD5 的文件对象
+     * @param chunkSize - 分片大小（字节），默认 2MB
+     * @returns Promise<string> 文件的 MD5 哈希值
+     *
+     * @example
+     * const md5 = await beLinkCOS.createFileMd5(file);
+     * console.log('文件 MD5:', md5);
+     */
+    createFileMd5(file: File, chunkSize?: number): Promise<string>;
+    /**
+     * 生成文件在 COS 中的存储路径
+     *
+     * 路径规则：/beLinkAllSource/static/{文件类型}/{文件名}_{时间戳}.{扩展名}
+     * 例如：/beLinkAllSource/static/image/avatar_1699999999999.png
+     *
+     * @param file - 文件对象
+     * @returns string COS 存储路径
+     */
+    private getFilePath;
+    /**
+     * 获取文件上传后的访问 URL（不执行实际上传）
+     *
+     * 用于在上传前预览文件的最终 URL
+     *
+     * @param file - 文件对象
+     * @returns Promise<string | null> 文件的完整访问 URL，如果实例未初始化则返回 null
+     *
+     * @example
+     * const url = await beLinkCOS.getSourceUrl(file);
+     * console.log('文件将上传到:', url);
+     */
+    getSourceUrl(file: File): Promise<string | null>;
+    /**
+     * 上传文件到腾讯云 COS
+     *
+     * 核心功能：将文件上传到对应环境的 COS 存储桶
+     * 支持上传进度回调、自定义请求头等配置
+     *
+     * @param file - 要上传的文件对象
+     * @param config - 上传配置（可选）
+     * @param config.Headers - 自定义请求头
+     * @param config.onProgressCallback - 上传进度回调函数
+     * @returns Promise<UploadResult> 上传结果，包含文件 URL、ETag 等信息
+     *
+     * @example
+     * const uploader = new BeLinkCOS({ mode: 'production' });
+     * const result = await uploader.uploadFile(file, {
+     *   onProgressCallback: (progressData) => {
+     *     console.log('进度:', progressData.percent * 100 + '%');
+     *   }
+     * });
+     * console.log('文件 URL:', result.url);
+     */
+    uploadFile(file: File, config?: UploadConfig): Promise<UploadResult>;
+    /**
+     * 销毁实例
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=beLinkCos.d.ts.map

package/dist/beLinkCos.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"beLinkCos.d.ts","sourceRoot":"","sources":["../src/beLinkCos.ts"],"names":[],"mappings":"AAIA,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEtE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,SAAS;IACpB,iBAAiB;IACjB,OAAO,CAAC,GAAG,CAAa;IACxB,kBAAkB;IAClB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAC/D,aAAa;IACN,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAM;IACzC,aAAa;IACN,IAAI,EAAE,OAAO,GAAG,IAAI,CAAQ;IACnC,oBAAoB;IACpB,OAAO,CAAC,UAAU,CAAkB;IACpC,aAAa;IACb,SAAS,CAAC,aAAa,EAAE,OAAO,CAAS;IACzC,SAAS,CAAC,WAAW,EAAE,OAAO,CAAS;IACvC,WAAW;IACX,OAAO,CAAC,KAAK,CAAkB;IAE/B;;;;;;;;;;;;;;;;;;;;OAoBG;gBACS,MAAM,CAAC,EAAE,UAAU;IAO/B;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAyB9B;;;;;;;OAOG;YACW,OAAO;IAqCrB;;OAEG;IACH,SAAS,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAYjD;;OAEG;IACH,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAMvC,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAMxC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAMzC;;OAEG;IACH,SAAS,CAAC,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO;IAmBrD;;OAEG;IACH,SAAS,IAAI;QAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAY/F;;;;;;;;;;;;;;OAcG;IACI,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,GAAE,MAAwB,GAAG,OAAO,CAAC,MAAM,CAAC;IA+DtF;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IASnB;;;;;;;;;;;OAWG;IACU,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAS7D;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAsCjF;;OAEG;IACH,OAAO,IAAI,IAAI;CAsBhB"}

package/dist/config.d.ts ADDED Viewed

@@ -0,0 +1,26 @@
+/**
+ * 环境模式类型
+ * - development: 开发环境
+ * - testing: 测试环境
+ * - production: 生产环境
+ */
+export type EnvMode = 'development' | 'testing' | 'production';
+/**
+ * COS 存储桶配置接口
+ */
+export interface BucketConfig {
+    /** 存储桶名称 */
+    name: string;
+    /** 存储桶访问域名 */
+    host: string;
+    /** 访问协议 */
+    protocol: string;
+}
+/**
+ * 各环境的 COS 存储桶配置
+ * 根据环境自动切换到对应的存储桶
+ */
+export declare const BUCKETS_CONFIG: Record<EnvMode, BucketConfig>;
+/** COS 存储桶所在地域（南京） */
+export declare const REGION: "ap-nanjing";
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,aAAa,GAAG,SAAS,GAAG,YAAY,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,YAAY;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,cAAc;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,OAAO,EAAE,YAAY,CAgBxD,CAAC;AAEF,sBAAsB;AACtB,eAAO,MAAM,MAAM,EAAG,YAAqB,CAAC"}