serverpod_cloud_storage_cos #

把腾讯云 COS 接入 Serverpod 官方 CloudStorage 接口的适配包。

兼容 Serverpod 官方文件上传流程（createDirectFileUploadDescription / FileUploader）。

dependencies:
  serverpod_cloud_storage_cos: ^0.1.0

配置 passwords.yaml #

在 config/passwords.yaml 里配置 COS 凭据：

shared:
  tencentCosSecretId: '<TENCENT_SECRET_ID>'
  tencentCosSecretKey: '<TENCENT_SECRET_KEY>'
  tencentCosBucket: '<COS_BUCKET_NAME>'
  tencentCosRegion: '<COS_REGION>'
  tencentCosCustomDomain: 'https://my-cdn.example.com' # 可选

在 server.dart 中启用 #

import 'package:serverpod/serverpod.dart';
import 'package:serverpod_cloud_storage_cos/serverpod_cloud_storage_cos.dart'
    as cos;

void run(List<String> args) async {
  final pod = Serverpod(args, Protocol(), Endpoints());

  // 替换默认 public 存储
  final cosBucket = pod.getPassword('tencentCosBucket');
  if (cosBucket == null || cosBucket.isEmpty) {
    throw StateError('tencentCosBucket must be configured in passwords.');
  }
  pod.addCloudStorage(
    cos.CosCloudStorage(
      serverpod: pod,
      storageId: 'public',
      public: true,
      region: pod.getPassword('tencentCosRegion') ?? 'ap-guangzhou',
      bucket: cosBucket,
      customDomain: pod.getPassword('tencentCosCustomDomain'),
    ),
  );

  // 必须：注册直传上传端点
  cos.registerCosCloudStorageEndpoint(pod);

  await pod.start();
}

客户端使用（官方方式） #

final desc = await client.myEndpoint.getUploadDescription('path/to/file.png');
if (desc != null) {
  final uploader = FileUploader(desc);
  await uploader.uploadByteData(byteData);
  await client.myEndpoint.verifyUpload('path/to/file.png');
}

说明 #

• 这是对 Serverpod 官方 CloudStorage 的兼容实现，接口与官方文档一致。
• 上传数据会先到你的服务端上传端点，再由服务端写入 COS。

维护与兼容性 #

• 版本策略：SemVer
• 反馈：issue / PR

参考 #

• Serverpod 官方对象存储文档：https://docs.serverpod.dev/concepts/file-uploads