更新记录

0.0.1（2026-01-23）

• init

平台兼容性

uni-app(4.76)

uni-app x(4.76)

lime-qcloud-cos

腾讯云对象存储（COS）uts 插件，支持 Android、iOS 和 Web 平台。

功能特性

• ✅ 文件上传（支持分块上传）
• ✅ 文件下载
• ✅ 文件删除
• ✅ 上传/下载进度监听
• ✅ 任务暂停/取消
• ✅ 跨平台支持（Android、iOS、Web）

安装

在 HBuilderX 中直接引入本插件即可。

使用方法

1. 初始化

import { useQCloud, type UseQCloudOptions } from '@/uni_modules/lime-qcloud-cos';

const options: UseQCloudOptions = {
  region: 'ap-guangzhou',           // 存储桶所属地域
  secretID: 'your-secret-id',       // 云 API 密钥 Id
  secretKey: 'your-secret-key',     // 云 API 密钥 key
  bucket: 'your-bucket',            // 存储桶名称
  startTime: Date.now() / 1000,     // 凭证开始时间（秒）
  expiredTime: Date.now() / 1000 + 3600, // 凭证过期时间（秒）
  token: 'your-token',              // 可选，临时凭证的 token
  keyPrefix: 'prefix/',             // 可选，文件键前缀
};

const cos = useQCloud(options);

2. 上传文件

import { type QCloudUploadFileOptions } from '@/uni_modules/lime-qcloud-cos';
// 方式1：使用 keyPrefix + fileName（推荐，简单）
const uploadTask = cos.uploadFile({
  filePath: '/path/to/file.jpg',    // 文件路径（App端）或 File 对象（Web端）
  fileName: 'example.jpg',          // 文件名
  success: (res) => {
    console.log('上传成功');
    console.log('文件路径:', res.location);  // COS 上的访问路径
    console.log('提示信息:', res.errMsg);    // "上传成功"
  },
  fail: (err) => {
    console.log('上传失败', err);
  }
} as QCloudUploadFileOptions);

// 方式2：指定完整 key（灵活，适合需要自定义路径的场景）
const uploadTask2 = cos.uploadFile({
  filePath: '/path/to/file.jpg',
  key: 'custom/folder/example.jpg',  // 完整 key（即 cosPath 的通用叫法）,会忽略 keyPrefix
  success: (res) => {
    console.log('上传成功到自定义路径');
  },
  fail: (err) => {
    console.log('上传失败', err);
  }
});

// 监听上传进度
uploadTask?.onProgressUpdate((progress) => {
  console.log(`上传进度: ${progress.progress.toFixed(2)}%`);
  console.log(`已上传: ${progress.totalBytesSent} 字节`);
  console.log(`总大小: ${progress.totalBytesExpectedToSend} 字节`);
});

// 控制上传任务
uploadTask?.pause();   // 暂停
uploadTask?.resume();  // 恢复
uploadTask?.abort();   // 取消

3. 下载文件

import { type QCloudDownloadFileOptions } from '@/uni_modules/lime-qcloud-cos';
const downloadTask = cos.downloadFile({
  url: 'path/to/file.jpg',          // 文件在 COS 上的对象键
  fileName: 'download.jpg',         // 保存的文件名
  success: (res) => {
    console.log('下载成功');
    console.log('本地路径:', res.tempFilePath);  // 本地临时文件路径
  },
  fail: (err) => {
    console.log('下载失败', err);
  }
} as QCloudDownloadFileOptions);

// 监听下载进度
downloadTask?.onProgressUpdate((progress) => {
  console.log(`下载进度: ${progress.progress.toFixed(2)}%`);
  console.log(`已下载: ${progress.totalDownload} 字节`);
  console.log(`总大小: ${progress.totalExpected} 字节`);
});

// 控制下载任务
downloadTask?.pause();   // 暂停
downloadTask?.resume();  // 恢复
downloadTask?.abort();   // 取消

4. 删除文件

import { type QCloudDeleteFileOptions } from '@/uni_modules/lime-qcloud-cos';
cos.deleteFile({
  key: 'path/to/file.jpg',          // 文件在 COS 上的对象键
  success: (res) => {
    console.log('删除成功');
    console.log('提示信息:', res.errMsg);    // "删除成功"
  },
  fail: (err) => {
    console.log('删除失败', err);
  }
} as QCloudDeleteFileOptions);

API 文档

类型定义

UseQCloudOptions

初始化配置选项：

QCloudUploadSuccess

上传成功返回结果：

QCloudDownloadSuccess

下载成功返回结果：

QCloudDeleteSuccess

删除成功返回结果：

QCloudUploadProgressResult

上传进度信息：

QCloudDownloadProgressResult

下载进度信息：

接口方法

useQCloud(options: UseQCloudOptions): QCloud

初始化 COS 实例。

uploadFile(options: QCloudUploadFileOptions): QCloudUploadTask | null

上传文件。

QCloudUploadFileOptions

上传文件参数：

说明：

• 如果指定了 key，则使用完整对象键，忽略 keyPrefix 和 fileName
• 如果未指定 key，则使用 keyPrefix + fileName 作为最终对象键

返回： QCloudUploadTask 对象，可用于控制上传任务和监听进度。

downloadFile(options: QCloudDownloadFileOptions): QCloudDownloadTask

下载文件。

参数：

• url: 文件在 COS 上的对象键
• fileName: 保存的文件名
• success: 成功回调
• fail: 失败回调

返回： QCloudDownloadTask 对象，可用于控制下载任务和监听进度。

deleteFile(options: QCloudDeleteFileOptions): void

删除文件。

参数：

• key: 文件在 COS 上的对象键
• success: 成功回调
• fail: 失败回调

错误码

平台兼容性

注意事项

1. 临时凭证安全：建议使用临时凭证（STS），不要在客户端暴露永久密钥
2. 文件路径差异：
   • App 端：filePath 为本地文件路径
   • Web 端：filePath 为 File 对象
3. 跨域配置：Web 端需要在 COS 控制台配置 CORS 规则
4. 分块上传：默认超过 10MB 的文件使用分块上传

开发文档

• UTS 语法
• UTS API插件
• UTS uni-app兼容模式组件
• UTS 标准模式组件
• Hello UTS
• 腾讯云 COS 文档

许可证

MIT

更新日志

1.0.0 (2026-01-21)

• ✨ 初始版本发布
• ✨ 支持 Android、iOS、Web 平台
• ✨ 实现文件上传、下载、删除功能
• ✨ 支持进度监听和任务控制