SDK 使用

PG 模式云存储推荐使用 app.storage.from(bucketId) 进入指定 Bucket 的对象操作客户端。路径参数均为 Bucket 内对象名，不需要传 cloud:// fileID。

import cloudbase from '@cloudbase/js-sdk';

const app = cloudbase.init({ env: '<env-id>' });
const bucket = app.storage.from('avatars');

选择合适的任务指南

你的目标	阅读建议
创建、更新、删除 Bucket	Bucket 管理
上传文件、处理 `contentType`、`upsert` 和元数据	上传文件
下载文件、生成签名链接、公开访问	访问与下载文件
列出、复制、移动、删除文件	管理文件
查询命名、大小、MIME、覆盖和路径设计建议	限制与最佳实践
CDN 缓存、Public / Private 缓存差异	CDN 加速与缓存
直接查 API 签名和类型定义	JS SDK Storage API

核心入口

const bucket = app.storage.from('avatars');

avatars 对应 storage.buckets.id。后续所有对象路径都相对于该 Bucket：

await bucket.upload('user-123/avatar.png', file);
await bucket.download('user-123/avatar.png');
await bucket.remove(['user-123/avatar.png']);

常用 API 速查

Bucket 管理

API	说明	文档
`app.storage.createBucket()`	创建 Bucket	Bucket 管理
`app.storage.updateBucket()`	更新 Bucket 配置	Bucket 管理
`app.storage.deleteBucket()`	删除 Bucket	Bucket 管理

文件上传

const { data, error } = await bucket.upload('user-123/avatar.png', file, {
  contentType: 'image/png',
  upsert: true,
  metadata: {
    usage: 'avatar',
  },
});

if (error) {
  throw error;
}

详细说明见上传文件。

访问与下载

const { data: blob } = await bucket.download('user-123/avatar.png');

const { data: signed } = await bucket.createSignedUrl('user-123/avatar.png', 600, {
  download: 'avatar.png',
});

const { data: publicUrl } = app.storage
  .from('public-assets')
  .getPublicUrl('logos/cloudbase.png');

详细说明见访问与下载文件。

文件管理

const list = await bucket.list('user-123', {
  limit: 20,
  withDelimiter: true,
});

await bucket.copy('user-123/a.png', 'user-123/b.png', { upsert: true });
await bucket.move('user-123/b.png', 'user-123/archive/b.png');
await bucket.remove(['user-123/archive/b.png']);

详细说明见管理文件。

权限与错误处理

所有 SDK 操作都会受 storage.objects / storage.buckets 上的 RLS Policy 控制：

SDK 操作	需要的主要权限
`upload()` 新建对象	`INSERT WITH CHECK`
`upload({ upsert: true })` 覆盖对象	`INSERT` 或 `UPDATE`，取决于对象是否已存在
`download()` / `createSignedUrl()`	`SELECT`
`list()` / `info()` / `exists()`	`SELECT`
`copy()`	源对象 `SELECT` + 目标路径 `INSERT` / `UPDATE`
`move()`	源对象 `SELECT` / `DELETE` + 目标路径 `INSERT` / `UPDATE`
`remove()`	`DELETE`

如果你遇到 403，优先检查当前登录态、对象路径、bucket_id 和对应 RLS Policy。详见权限管理与常见问题。

AI 友好提示

让 AI 生成 SDK 代码时，建议同时提供 Bucket 契约和期望操作。例如：

Bucket: private-files
路径模板：<uid>/<filename>
操作：上传 PDF 后生成 10 分钟签名下载链接
权限：仅 owner 可上传、读取、删除
限制：20 MB；application/pdf
SDK：使用 @cloudbase/js-sdk 的 app.storage.from('private-files')

这样 AI 更容易选择正确的 bucketId、路径格式、SDK 方法和错误处理方式。

选择合适的任务指南​

核心入口​

常用 API 速查​

Bucket 管理​

文件上传​

访问与下载​

文件管理​

权限与错误处理​

AI 友好提示​

相关资源​