@cloudbase/storage
CloudBase JS SDK 的存储模块。通过组件机制注册到 cloudbase app 上,对外暴露两套并存的 API:
- 经典顶层 API:
app.uploadFile()/app.downloadFile()…(传统云存储能力,直接挂在 app 实例上)。 app.storage命名空间:Supabase-style 的对象操作 + Bucket 管理。
模块自身不直接被业务
import,而是通过registerStorage(app)(或自动注册)把能力注入到app上。对外类型定义见packages/cloudbase/index.d.ts。
一、暴露的 API 结构
app
├─ uploadFile() ← 经典顶层 API(CloudbaseStorage 提供)
├─ downloadFile()
├─ copyFile()
├─ getTempFileURL()
├─ deleteFile()
├─ getFileInfo()
├─ getUploadMetadata()
├─ isGateWay()
│
└─ storage : StorageClient
├─ throwOnError()
├─ from() → ClassicStorageFileApi ← 传统环境对象操作
│
├─ from(bucketId) → StorageFileApi ← Neo 环境原生对象操作
├─ listBuckets() ← Bucket 管理(仅 Neo 环境)
├─ getBucket(bucketId)
├─ createBucket(bucketId)
├─ updateBucket(bucketId)
└─ deleteBucket(bucketId)
1. 经典顶层 API(app.*)
由 CloudbaseStorage 类提供的云存储 HTTP 接口。
⚠️ 已标为废弃:
app.uploadFile/downloadFile/deleteFile/getTempFileURL/getUploadMetadata/copyFile/getFileInfo等传统顶层 API 已不推荐使用,请改用app.storage.from()提供的对象存储 API(upload/download/remove/createSignedUrl/createSignedUploadUrl/copy/info等)。
| 方法 | 说明 |
|---|---|
uploadFile(params, cb?) | 上传文件 |
downloadFile(params, cb?) | 下载文件 |
deleteFile(params, cb?) | 批量删除 |
getTempFileURL(params, cb?) | 获取临时下载链接 |
getUploadMetadata(params, cb?) | 获取上传元信息 |
copyFile(params, cb?) | 批量复制 |
getFileInfo(params) | 获取文件信息 |
isGateWay() | 是否网关模式(内部用) |
2. app.storage:分流器(StorageClient)
继承 StorageBucketApi(Bucket 管理),并提供 from() 分流。
Bucket 管理:
| 方法 | 说明 | 返回 |
|---|---|---|
throwOnError() | 开启抛错模式(链式),失败时抛异常;成功仍返回 { data, error: null } | this |
listBuckets(options?) | 获取 Bucket 列表,支持偏移分页、排序和搜索 | { data: Bucket[], error } |
getBucket(bucketId) | 获取指定 Bucket 详情 | { data: Bucket, error } |
createBucket(bucketId, options?) | 创建 Bucket | { data: { name }, error } |
updateBucket(bucketId, options) | 更新 Bucket 配置;不支持更新 type | { data: { message }, error } |
deleteBucket(bucketId) | 删除空 Bucket | { data: { message }, error } |
Bucket 返回字段:
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | Bucket ID |
name | string | Bucket 名称 |
owner_id | string | null | 创建者用户 ID;可能为空 |
public | boolean | 是否为公开 Bucket |
type | 'STANDARD' | Bucket 类型 |
file_size_limit | number | null | 文件大小限制,单位为字节;null 表示不限制 |
allowed_mime_types | string[] | null | 允许上传的 MIME 类型列表;null 表示不限制 |
created_at | string | 创建时间,ISO 8601 日期时间字符串 |
updated_at | string | 更新时间,ISO 8601 日期时间字符串 |
Bucket 列表参数:
| 参数 | 类型 | 说明 |
|---|---|---|
limit | number | 返回数量限制 |
offset | number | 分页偏移量 |
sortColumn | 'id' | 'name' | 'created_at' | 'updated_at' | 排序字段 |
sortOrder | 'asc' | 'desc' | 排序方向 |
search | string | 按关键词搜索 Bucket |
Bucket 创建 / 更新参数:
| 参数 | 类型 | createBucket | updateBucket | 说明 |
|---|---|---|---|---|
public | boolean | ✓ | ✓ | 是否公开,创建时默认 false |
fileSizeLimit | number | string | null | ✓ | ✓ | 文件大小限制;数字按字节处理,字符串支持如 100MB,null 表示不限制 |
allowedMimeTypes | string[] | null | ✓ | ✓ | 允许上传的 MIME 类型列表,null 表示不限制 |
type | 'STANDARD' | ✓ | — | Bucket 类型,仅创建时可传 |
示例:
const storage = app.storage
const { data: buckets, error } = await storage.listBuckets({
limit: 20,
offset: 0,
sortColumn: 'created_at',
sortOrder: 'desc',
search: 'avatar',
})
if (error) throw error
await storage.createBucket('avatars', {
public: false,
type: 'STANDARD',
fileSizeLimit: '100MB',
allowedMimeTypes: ['image/png', 'image/jpeg'],
})
await storage.getBucket('avatars')
await storage.updateBucket('avatars', {
public: true,
fileSizeLimit: null,
allowedMimeTypes: null,
})
await storage.deleteBucket('avatars')
限制与差异:
- Bucket 管理能力的权限由
storage.buckets的 RLS Policy 决定。 deleteBucket()仅能删除空 Bucket;非空时后端会返回错误。- 暂不提供
emptyBucket();OpenAPI 当前没有原子清空 Bucket 端点,SDK 不循环批量删除来伪造该能力。 - 暂不提供
headBucket/existsBucket/ Bucket CORS / Bucket ACL 等 COS/S3 风格 Bucket 管理 API。
from() 分流到两个对等且独立的对象操作客户端:
app.storage.from() // → ClassicStorageFileApi(传统环境)
app.storage.from('avatars') // → StorageFileApi(Neo 环境)
3. from() 返回的两个对象操作客户端
两者均为 Supabase 风格签名、对等且独立:
from()→ClassicStorageFileApi(传统环境):底层走传统云存储 HTTP API(委托内部持有的CloudbaseStorage)。无 Bucket 概念,download/remove/getPublicUrl等需传 upload 返回的完整fileID。所有环境可用。from(bucketId)→StorageFileApi(Neo 环境):bucketId + objectName语义,走 PG 原生/object/{bucketId}/{name}通道,bucketId必填(不传将抛错)。仅 Neo 环境可用。
下表对比两者差异:
| 方法 | from()·ClassicStorageFileApi(传统环境) | from(bucketId)·StorageFileApi(PG 原生) |
|---|---|---|
throwOnError() | 链式 | 链式 |
setHeader(name, value) | — | 设置实例级自定义请求头(链式) |
upload(path, fileBody, fileOptions?) | 默认 upsert: true | 默认不覆盖 |
update(path, fileBody, fileOptions?) | 强制覆盖 | 等同 upsert |
uploadToSignedUrl(path, token, fileBody, fileOptions?) | token 被忽略,委托 upload | ✓ |
createSignedUploadUrl(path, options?) | 仅 (path);额外返回 CloudBase 私有字段 | 支持 options.upsert |
move(fromPath, toPath, options?) | 仅 (fromPath, toPath);复制后删源 | 支持 options |
copy(fromPath, toPath, options?) | 仅 (fromPath, toPath) | 支持 options |
createSignedUrl(path, expiresIn, options?) | expiresIn 传入无效(传统模式不支持指定 TTL);transform 走数据万象 imageMogr2 | 仅支持 download,不支持 transform;expiresIn 有效 |
createSignedUrls(paths, expiresIn, options?) | 仅 (paths, expiresIn);expiresIn 传入无效 | 支持 download;expiresIn 有效 |
download(path, options?, parameters?) | 仅 (path, options?);返回 { data: Blob; error } | 第三参 parameters 支持 signal/cache |
list(path?, options?, parameters?) | 未实现(抛错) | 游标分页 |
info(path) | 入参 pathOrFileId;返回 Camelize<FileObjectV2> | 返回 ObjectInfo |
exists(path) | 入参 pathOrFileId | ✓ |
getPublicUrl(path, options?) | 异步;实为 600s 签名 URL | 同步 返回 { data: { publicUrl } },仅支持 download |
remove(paths) | 返回 FileObject[] | string | string[],返回 FullObject[] |
from(bucketId) 的详细 Object API、参数与返回值见下文「三、Object 操作」。
二、Bucket 管理
Bucket 管理请求会携带当前 SDK 登录态,最终是否允许执行由后端和
storage.buckets的 RLS Policy 决定。
Bucket 管理 API 直接挂在 app.storage 上,用于管理 storage.buckets 资源:
const storage = app.storage
const { data: buckets, error } = await storage.listBuckets({
limit: 20,
offset: 0,
sortColumn: 'created_at',
sortOrder: 'desc',
search: 'avatar',
})
if (error) {
throw error
}
await storage.createBucket('avatars', {
public: false,
type: 'STANDARD',
fileSizeLimit: '100MB',
allowedMimeTypes: ['image/png', 'image/jpeg'],
})
await storage.getBucket('avatars')
await storage.updateBucket('avatars', {
public: true,
fileSizeLimit: null,
allowedMimeTypes: null,
})
await storage.deleteBucket('avatars')
API
| API | 说明 | 成功返回 |
|---|---|---|
storage.listBuckets(options?) | 获取 Bucket 列表,支持 limit / offset / sortColumn / sortOrder / search | Bucket[] |
storage.getBucket(bucketId) | 获取指定 Bucket 详情 | Bucket |
storage.createBucket(bucketId, options?) | 创建 Bucket,bucketId 同时作为后端 id 与 name | { name: string } |
storage.updateBucket(bucketId, options) | 更新 Bucket 配置;不支持更新 type | { message: string } |
storage.deleteBucket(bucketId) | 删除空 Bucket | { message: string } |
参数
listBuckets(options):
| 参数 | 类型 | 说明 |
|---|---|---|
limit | number | 返回数量限制 |
offset | number | 分页偏移量 |
sortColumn | 'id' | 'name' | 'created_at' | 'updated_at' | 排序字段 |
sortOrder | 'asc' | 'desc' | 排序方向 |
search | string | 搜索关键词 |
createBucket(bucketId, options) / updateBucket(bucketId, options):
| 参数 | 类型 | 创建 | 更新 | 说明 |
|---|---|---|---|---|
public | boolean | ✓ | ✓ | 是否公开,创建时默认 false |
fileSizeLimit | number | string | null | ✓ | ✓ | 文件大小限制;数字按字节处理,字符串支持如 100MB,null 表示不限制 |
allowedMimeTypes | string[] | null | ✓ | ✓ | 允许上传的 MIME 类型列表,null 表示不限制 |
type | 'STANDARD' | ✓ | — | Bucket 类型,仅创建时可传 |
返回值
listBuckets() 与 getBucket() 返回 Bucket 或 Bucket[]:
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | Bucket ID |
name | string | Bucket 名称 |
owner_id | string | null | 创建者用户 ID;可能为空 |
public | boolean | 是否为公开 Bucket |
type | 'STANDARD' | Bucket 类型 |
file_size_limit | number | null | 文件大小限制,单位为字节;null 表示不限制 |
allowed_mime_types | string[] | null | 允许上传的 MIME 类型列表;null 表示不限制 |
created_at | string | 创建时间,ISO 8601 日期时间字符串 |
updated_at | string | 更新时间,ISO 8601 日期时间字符串 |
错误处理
默认返回 { data, error }:
const { data, error } = await storage.getBucket('avatars')
if (error) {
console.error(error.message)
return
}
console.log(data.name)
也可以使用 throwOnError(),开启后失败会抛异常,成功仍返回 { data, error: null }:
const { data } = await storage.throwOnError().getBucket('avatars')
限制
deleteBucket()只能删除空 Bucket;非空时后端会返回错误。- 暂不提供
emptyBucket()。当前 OpenAPI 没有原子清空 Bucket 端点,SDK 不会循环批量删除来伪造该能力。 - 暂不提供
headBucket/existsBucket/ Bucket CORS / Bucket ACL 等 COS/S3 风格 Bucket 管理 API。
三、Object 操作
通过
app.storage.from(bucketId)获取单 Bucket 对象操作客户端;后续所有path/objectName都是 Bucket 内相对路径,不再包含bucketId。
快速示例:
const avatars = app.storage.from('avatars')
await avatars.upload('users/u1/avatar.png', file, {
contentType: 'image/png',
cacheControl: '3600',
upsert: true,
metadata: { source: 'web' },
})
// 断点续传。浏览器刷新后可续;Node 只在当前进程内可续。
const task = avatars.uploadResumable('users/u1/video.mp4', file, {
contentType: file.type,
upsert: true,
onProgress: (loaded, total) => console.log(loaded, total),
})
const { data: resumed } = await task
// 取消并通知服务端终止会话:await task.abort(true)
await avatars.update('users/u1/avatar.png', file)
const { data: blob } = await avatars.download('users/u1/avatar.png')
// 流式下载(适合 Node 大文件,避免整体读入内存)
const { data: stream } = await avatars.download('users/u1/big.zip').asStream()
const { data: list } = await avatars.list('users/u1/', {
limit: 100,
withDelimiter: true,
sortBy: { column: 'created_at', order: 'desc' },
})
await avatars.info('users/u1/avatar.png')
await avatars.exists('users/u1/avatar.png')
await avatars.remove(['users/u1/avatar.png'])
复制 / 移动:
await avatars.copy('users/u1/avatar.png', 'backup/u1/avatar.png', {
destinationBucket: 'backup',
upsert: true,
copyMetadata: false,
metadata: { copiedBy: 'web' },
})
await avatars.move('backup/u1/avatar.png', 'archive/u1/avatar.png')
签名 URL 与公开 URL:
await avatars.createSignedUrl('users/u1/avatar.png', 3600, {
download: true,
})
await avatars.createSignedUrls(['a.png', 'b.png'], 3600, {
download: true,
})
const signedUpload = await avatars.createSignedUploadUrl('uploads/avatar.png', {
upsert: true,
})
if (signedUpload.data) {
await avatars.uploadToSignedUrl('uploads/avatar.png', signedUpload.data.token, file, {
contentType: 'image/png',
})
}
const { data } = avatars.getPublicUrl('users/u1/avatar.png', {
download: true,
})
console.log(data.publicUrl)
Object API
| API | 说明 | 成功返回 |
|---|---|---|
from(bucketId).upload(path, fileBody, options?) | 上传对象;默认不覆盖同名对象 | UploadResult |
from(bucketId).uploadResumable(path, fileBody, options?) | TUS 断点续传。浏览器用 localStorage;Node 只用进程内存储。await 得到结果,abort(true) 终止会话 | ResumableUploadResult |
from(bucketId).update(path, fileBody, options?) | 覆盖更新对象 | UploadResult |
from(bucketId).download(path, options?, parameters?) | 下载对象,返回 thenable 构建器;await 得 Blob,.asStream() 得 ReadableStream | Blob / ReadableStream |
from(bucketId).list(path?, options?, parameters?) | 获取对象列表;游标分页,返回列表结构 | ListObjectsResponse |
from(bucketId).remove(paths) | 删除一个或多个对象;超过 100 个时 SDK 自动分批 | FullObject[] |
from(bucketId).copy(fromPath, toPath, options?) | 复制对象,支持跨 Bucket | { path: string } |
from(bucketId).move(fromPath, toPath, options?) | 移动对象,支持跨 Bucket | { message: string } |
from(bucketId).info(path) | 获取对象元信息 | ObjectInfo |
from(bucketId).exists(path) | 判断对象是否存在 | boolean |
from(bucketId).createSignedUrl(path, expiresIn, options?) | 生成单个签名下载 URL | { fullSignedURL: string } |
from(bucketId).createSignedUrls(paths, expiresIn, options?) | 批量生成签名下载 URL;超过 500 个时 SDK 自动分批 | SignedUrlsResultItem[] |
from(bucketId).createSignedUploadUrl(path, options?) | 生成签名上传 URL | { fullSignedURL, token, path } |
from(bucketId).uploadToSignedUrl(path, token, fileBody, options?) | 使用签名上传 token 上传对象,无需登录态 | { path, fullPath } |
from(bucketId).getPublicUrl(path, options?) | 同步拼接 public bucket 公开 URL,不发请求、不返回 error | { data: { publicUrl } } |
from(bucketId).setHeader(name, value) | 设置自定义请求头,对当前实例后续请求生效(链式) | this |
Object 参数
上传选项 FileOptions:
| 参数 | 类型 | 说明 |
|---|---|---|
cacheControl | string | 缓存时间,单位为秒;默认 3600 |
contentType | string | 文件 MIME 类型;非 Blob / File / FormData 时建议显式指定 |
upsert | boolean | 是否允许覆盖同名对象;upload() 默认 false,update() 等同覆盖 |
metadata | Record<string, any> | 用户自定义元数据 |
headers | Record<string, string> | 额外请求头 |
duplex | string | 透传给底层 fetch 的 duplex 配置 |
下载选项 DownloadOptions:
| 参数 | 类型 | 说明 |
|---|---|---|
download | string | boolean | 触发浏览器下载;字符串值作为下载文件名 |
cacheNonce | string | 缓存失效 nonce,追加到请求 URL 以绕过 CDN 缓存 |
列表选项 ListOptions:
| 参数 | 类型 | 说明 |
|---|---|---|
limit | number | 返回数量限制,后端最大值为 1000 |
cursor | string | 翻页游标,由上一页响应的 nextCursor 提供 |
withDelimiter | boolean | 是否使用 / 作为分隔符区分文件夹 |
sortBy.column | 'name' | 'created_at' | 'updated_at' | 排序字段 |
sortBy.order | 'asc' | 'desc' | 排序方向 |
复制 / 移动选项 DestinationOptions:
| 参数 | 类型 | 说明 |
|---|---|---|
destinationBucket | string | 目标 Bucket ID,默认与源 Bucket 相同 |
upsert | boolean | 允许覆盖目标位置已有对象;用于 copy() |
copyMetadata | boolean | 是否复制源对象元数据;用于 copy(),默认由后端决定 |
metadata | Record<string, any> | copyMetadata=false 时合并到目标对象的用户元数据 |
签名 / 公开 URL 选项:
| 参数 | 类型 | 说明 |
|---|---|---|
download | string | boolean | 触发浏览器下载;字符串值作为下载文件名 |
请求控制参数 FetchParameters:
| 参数 | 类型 | 说明 |
|---|---|---|
signal | AbortSignal | 请求取消信号 |
cache | RequestCache | 透传给底层 fetch 的缓存策略;部分运行时可能忽略 |
Object 返回值
UploadResult:
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 对象 UUID |
path | string | Bucket 内相对路径 |
fullPath | string | 对象完整路径 bucketId/objectName |
ListObjectsResponse:
| 字段 | 类型 | 说明 |
|---|---|---|
folders | ListObjectsEntry[] | 当前前缀下的文件夹条目 |
objects | ListObjectsEntry[] | 当前前缀下的对象条目 |
hasNext | boolean | 是否还有下一页 |
nextCursor | string | 下一页游标 |
nextCursorKey | string | 下一页起始 key |
ListObjectsEntry:
| 字段 | 类型 | 说明 |
|---|---|---|
key | string | null | 对象完整 key;文件夹条目可能为空 |
name | string | 对象名或文件夹名 |
id | string | null | 对象 UUID;文件夹条目可能为空 |
updated_at | string | null | 更新时间 |
created_at | string | null | 创建时间 |
last_accessed_at | string | null | 最后访问时间 |
metadata | Record<string, any> | null | 对象元数据 |
ObjectInfo:
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 对象 UUID |
name | string | Bucket 内相对路径 |
version | string | null | 对象版本标识;可能为空 |
bucketId | string | 所属 Bucket ID |
size | number | null | 文件大小,单位为字节 |
contentType | string | null | 文件 MIME 类型 |
cacheControl | string | null | 缓存控制信息 |
etag | string | null | 对象 ETag |
metadata | Record<string, any> | 用户自定义元数据 |
lastModified | string | null | 最后修改时间 |
createdAt | string | null | 创建时间 |
FullObject:
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | Bucket 内相对路径 |
bucket_id | string | 所属 Bucket ID |
owner_id | string | null | 创建者用户 ID;可能为空 |
version | string | null | 对象版本标识;可能为空 |
id | string | null | 对象 UUID;可能为空 |
updated_at | string | null | 更新时间 |
created_at | string | null | 创建时间 |
last_accessed_at | string | null | 最后访问时间 |
metadata | Record<string, any> | 系统或对象元数据 |
user_metadata | Record<string, any> | 用户自定义元数据 |
SignedUrlsResultItem:
| 字段 | 类型 | 说明 |
|---|---|---|
path | string | 请求签名的对象路径 |
signedUrl | string | null | 签名下载 URL;生成失败时为 null |
error | string | null | 单项错误信息;成功时为 null |
CreateSignedUploadUrlResult:
| 字段 | 类型 | 说明 |
|---|---|---|
signedUrl | string | 签名上传 URL |
token | string | 签名上传 token |
path | string | Bucket 内相对路径 |
uploadToSignedUrl() 返回:
| 字段 | 类型 | 说明 |
|---|---|---|
path | string | Bucket 内相对路径 |
fullPath | string | 对象完整路径 bucketId/objectName |
错误处理与限制
- 除
getPublicUrl()外,默认返回{ data, error };getPublicUrl()是同步方法,只返回{ data: { publicUrl } }。 throwOnError()开启后失败会抛异常,成功仍保持{ data, error: null }返回结构。- 所有
path/objectName都是 Bucket 内相对路径,不能包含bucketId前缀。 list()是游标分页结构,不是传统 offset 分页的FileObject[]。remove()后端单次最多 100 个对象,SDK 会自动分批。createSignedUrls()后端单次最多 500 个对象,SDK 会自动分批。download()当前返回Blob,不返回 HTTP status / headers。createSignedUrl()、createSignedUrls()、getPublicUrl()当前仅支持download选项,不支持图片transform。setHeader()对当前实例后续所有请求生效;单次请求内部的功能性头(如Content-Type/x-upsert)优先级更高,会覆盖同名头。