flutter_cos_client

一个用于上传文件到腾讯云 COS（对象存储）的 Flutter 插件，（目前仅支持putObject功能）。

English | 简体中文

特性

• ✅ 支持使用永久密钥上传文件
• ✅ 支持使用临时密钥上传文件（推荐）
• ✅ 自动缓存临时密钥，避免重复请求
• ✅ 支持上传进度回调
• ✅ 支持字节数据上传（Base64、内存数据等）
• ✅ 支持本地文件上传
• ✅ 自动识别文件 MIME 类型
• ✅ 支持中文文件名和路径
• ✅ 完整的腾讯云签名算法实现

安装

在 pubspec.yaml 中添加依赖：

dependencies:
  flutter_cos_client: ^0.0.1

使用方法

方式一：上传本地文件（使用永久密钥）

import 'dart:io';
import 'package:flutter_cos_client/flutter_cos_client.dart';

Future<void> main() async {
  // 创建 COS 客户端
  final cosClient = CosClient(
    secretId: 'YOUR_SECRET_ID',
    secretKey: 'YOUR_SECRET_KEY',
    region: 'ap-guangzhou',
    bucket: 'your-bucket-1250000000',
  );

  // 上传文件
  final file = File('/path/to/your/file.png');
  final result = await cosClient.putObjectFromFile(
    objectKey: 'folder/file.png',
    file: file,
    onProgress: (count, total) {
      print('上传进度: ${(count / total * 100).toStringAsFixed(2)}%');
    },
  );

  if (result.success) {
    print('上传成功！文件地址: ${result.url}');
  } else {
    print('上传失败: ${result.message}');
  }
}

方式二：上传字节数据（支持内存、Base64 等）

import 'dart:convert';
import 'package:flutter_cos_client/flutter_cos_client.dart';

Future<void> main() async {
  final cosClient = CosClient(
    secretId: 'YOUR_SECRET_ID',
    secretKey: 'YOUR_SECRET_KEY',
    region: 'ap-guangzhou',
    bucket: 'your-bucket-1250000000',
  );

  // 示例1: 上传文本字节
  final textBytes = utf8.encode('Hello, COS!');
  final result1 = await cosClient.putObject(
    objectKey: 'test/hello.txt',
    fileBytes: textBytes,
    fileName: 'hello.txt', // 用于自动推断 Content-Type
  );

  // 示例2: 上传 Base64 数据
  final base64String = 'iVBORw0KGgoAAAANS...'; // Base64 字符串
  final base64Bytes = base64.decode(base64String);
  final result2 = await cosClient.putObject(
    objectKey: 'test/image.png',
    fileBytes: base64Bytes,
    contentType: 'image/png', // 直接指定 Content-Type
  );

  print('上传成功！文件地址: ${result2.url}');
}

方式三：使用临时密钥（推荐用于生产环境）

临时密钥更加安全，适合在客户端使用。

import 'dart:io';
import 'package:dio/dio.dart';
import 'package:flutter_cos_client/flutter_cos_client.dart';

Future<void> main() async {
  // 创建临时密钥提供者
  final credentialProvider = TemporaryCredentialProvider(
    fetchCredentials: () async {
      // 从你的服务器获取临时密钥
      final dio = Dio();
      final response = await dio.get('https://your-api.com/cos/credentials');
      return CosCredentialData.fromJson(response.data);
    },
  );

  // 使用临时密钥创建 COS 客户端
  final cosClient = CosClient.withTemporaryCredential(
    temporaryCredentialProvider: credentialProvider,
    region: 'ap-guangzhou',
    bucket: 'your-bucket-1250000000',
  );

  // 上传文件
  final file = File('/path/to/your/file.png');
  final result = await cosClient.putObjectFromFile(
    objectKey: 'folder/file.png',
    file: file,
    onProgress: (count, total) {
      print('上传进度: ${(count / total * 100).toStringAsFixed(2)}%');
    },
  );

  if (result.success) {
    print('上传成功！文件地址: ${result.url}');
  }
}

服务端临时密钥接口

如果使用临时密钥方式，你需要在服务端提供一个接口返回临时凭据。返回的数据格式应符合以下结构：

{
  "startTime": 1634567890,
  "expiredTime": 1634571490,
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "credentials": {
    "tmpSecretId": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "tmpSecretKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "sessionToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

TypeScript 类型定义（参考）

export class CosCredential {
  tmpSecretId: string;
  tmpSecretKey: string;
  sessionToken: string;
}

export class CosCredentialData {
  startTime: number;        // UNIX 时间戳（秒）
  expiredTime: number;      // UNIX 时间戳（秒）
  credentials: CosCredential;
  requestId: string;
}

API 文档

CosClient

构造函数

• CosClient({...}) - 使用永久密钥创建客户端
• CosClient.withTemporaryCredential({...}) - 使用临时密钥提供者创建客户端

方法

• putObject({...}) - 上传字节数据到 COS

  • objectKey - 对象键（必填）
  • fileBytes - 文件字节数据（必填）
  • fileName - 文件名，用于自动推断 Content-Type（可选）
  • contentType - Content-Type（可选）
  • onProgress - 上传进度回调（可选）

• putObjectFromFile({...}) - 从本地文件上传到 COS（便捷方法）

  • objectKey - 对象键（必填）
  • file - File 对象（必填）
  • contentType - Content-Type（可选）
  • onProgress - 上传进度回调（可选）

TemporaryCredentialProvider

临时密钥提供者，会自动缓存凭据，在有效期内避免重复请求。

构造函数

• TemporaryCredentialProvider({required fetchCredentials}) - 创建临时密钥提供者

方法

• getCredentials() - 获取有效的临时凭据（自动处理缓存）
• clearCache() - 清除缓存的凭据

注意事项

1. 安全性：永久密钥不应在客户端代码中硬编码，推荐使用临时密钥方式
2. 缓存机制：临时密钥会在内存中缓存，过期前 5 分钟会自动刷新
3. 地域设置：确保 region 和 bucket 的设置与腾讯云控制台一致

常见问题

如何获取腾讯云 COS 的 SecretId 和 SecretKey？

1. 登录 腾讯云控制台
2. 进入访问管理 -> API 密钥管理
3. 创建或查看现有的 API 密钥

为什么推荐使用临时密钥？

临时密钥具有以下优势：

• 有效期短，即使泄露也能快速失效
• 可以精确控制权限范围
• 不会暴露永久密钥
• 符合腾讯云安全最佳实践

如何实现服务端临时密钥接口？

请参考腾讯云官方文档：临时密钥生成及使用指引

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License - 详见 LICENSE 文件

相关链接

• 腾讯云 COS 文档
• 临时密钥生成指引
• API 签名文档