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

@be-link/cos 1.11.4 → 1.11.5-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 (15) hide show

package/README.md CHANGED Viewed

@@ -1,11 +1,335 @@
-# `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>
+```
+### 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 上传器实例
+**参数：**
+- `config.mode` - **必填，无默认值**
+  - 环境模式：`'development'` | `'testing'` | `'production'`
+  - 设计上强制必填，避免误传到错误环境
+- `config.headers` - 可选，自定义请求头
+- `config.ScopeLimit` - 可选，是否限制临时密钥范围（默认 `false`）
+**示例：**
+```typescript
+// 基础使用
+const uploader = new BeLinkCOS({ mode: 'production' });
+// 带自定义请求头
+const uploader = new BeLinkCOS({
+  mode: 'production',
+  headers: { 'x-custom': 'value' },
+});
+```
+### `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 分片
+```
+---
+## 环境配置
+| 环境        | 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. 为什么 mode 必须传？没有默认值？
+**设计理念：强制显式配置，避免默认值陷阱**
+如果提供默认值（如 `development`），很容易出现以下问题：
+- 开发者忘记修改配置，生产环境代码误传到开发环境
+- 或者开发环境配置被复制到生产，导致测试数据污染生产环境
+**因此，我们要求必须显式指定环境：**
+```typescript
+// ✅ 正确：明确指定环境，不会搞错
+const uploader = new BeLinkCOS({ mode: 'production' });
+// ❌ 错误：TypeScript 编译错误，强制必须传 mode
+const uploader = new BeLinkCOS();
+```
+这样设计更安全，用户必须思考"我要上传到哪个环境"。
+### 2. 上传失败怎么办？
+检查：
+- `mode` 参数是否正确
+- 网络是否正常
+- 浏览器控制台是否有错误信息
+### 3. 文件存储路径是什么？
+文件会自动存储到：`/beLinkAllSource/static/{文件类型}/{文件名}_{时间戳}.{扩展名}`
+例如：`/beLinkAllSource/static/image/avatar_1699999999999.png`
+### 4. 支持哪些文件类型？
+支持所有文件类型，会根据文件的 MIME 类型自动分类存储（image、video、audio、application、text、other）。
+### 5. 如何切换环境？
+创建不同环境的实例：
+```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,118 @@
-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);
+ */
+export declare class BeLinkCOS {
+    /** COS SDK 实例 */
+    private cos;
+    /** COS 存储的基础路径 */
+    private readonly basePath;
+    /** 自定义请求头 */
+    headers: Record<string, any>;
+    /** 当前环境模式 */
+    mode: EnvMode;
+    /** 是否限制临时密钥的使用范围 */
+    private scopeLimit;
+    /**
+     * 构造函数
+     *
+     * 注意：mode 参数必填，没有默认值
+     * 设计理念：强制显式配置环境，避免误传到错误的环境
+     *
+     * @param config - 初始化配置
+     * @param config.mode - **必填** 环境模式：'development' | 'testing' | 'production'
+     * @param config.headers - 可选，自定义请求头
+     * @param config.ScopeLimit - 可选，是否限制临时密钥的使用范围（默认 false）
+     *
+     * @example
+     * // 基础使用
+     * const uploader = new BeLinkCOS({ mode: 'production' });
+     *
+     * // 带自定义请求头
+     * const uploader = new BeLinkCOS({
+     *   mode: 'production',
+     *   headers: { 'x-custom': 'value' }
+     * });
+     */
+    constructor(config: InitConfig);
+    /**
+     * 初始化 COS SDK 实例
+     *
+     * 内部方法，通过云函数获取临时密钥
+     * 首次上传时会自动调用，也可以手动调用以重新初始化
+     *
+     * @returns Promise<void>
+     */
+    private initCOS;
+    /**
+     * 计算文件的 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 Promise<string> COS 存储路径
+     */
+    private getFilePath;
+    /**
+     * 获取文件上传后的访问 URL（不执行实际上传）
+     *
+     * 用于在上传前预览文件的最终 URL
+     *
+     * @param file - 文件对象
+     * @returns Promise<string> 文件的完整访问 URL
+     *
+     * @example
+     * const url = await beLinkCOS.getSourceUrl(file);
+     * console.log('文件将上传到:', url);
+     */
+    getSourceUrl(file: File): Promise<string>;
+    /**
+     * 上传文件到腾讯云 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>;
+}
+//# 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":"AAGA,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEtE;;;;;;;;;;GAUG;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,CAAC;IACpC,aAAa;IACN,IAAI,EAAE,OAAO,CAAC;IACrB,oBAAoB;IACpB,OAAO,CAAC,UAAU,CAAU;IAE5B;;;;;;;;;;;;;;;;;;;;OAoBG;gBACS,MAAM,EAAE,UAAU;IAM9B;;;;;;;OAOG;YACW,OAAO;IAoCrB;;;;;;;;;;;;;;OAcG;IACI,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,GAAE,MAAwB,GAAG,OAAO,CAAC,MAAM,CAAC;IA+DtF;;;;;;;;OAQG;YACW,WAAW;IASzB;;;;;;;;;;;OAWG;IACU,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAKtD;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;CA6BlF"}

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"}

package/dist/index.d.ts CHANGED Viewed

@@ -1 +1,5 @@
-export { default as beLinkCOS } from './beLinkCos';
+export { BeLinkCOS } from './beLinkCos';
+export type { EnvMode, BucketConfig } from './config';
+export { BUCKETS_CONFIG, REGION } from './config';
+export type { InitConfig, UploadConfig, UploadResult } from './types';
+//# sourceMappingURL=index.d.ts.map

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

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGlD,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}