@cloudbase/storage

中文文档
3.9.3发布于 2026/11/16Apache-2.0TypeScriptESM + CJS近 30 天下载 1.3万

云库 js sdk 存储模块

中文使用文档
文档目录15 节
  1. 一、暴露的 API 结构
  2. 1. 经典顶层 API( app.* )
  3. 2. app.storage :分流器( StorageClient )
  4. 3. from() 返回的两个对象操作客户端
  5. 二、Bucket 管理
  6. API
  7. 参数
  8. 返回值
  9. 错误处理
  10. 限制
  11. 三、Object 操作
  12. Object API
  13. Object 参数
  14. Object 返回值
  15. 错误处理与限制

@cloudbase/storage

CloudBase JS SDK 的存储模块。通过组件机制注册到 cloudbase app 上,对外暴露两套并存的 API:

  1. 经典顶层 API:app.uploadFile() / app.downloadFile() …(传统云存储能力,直接挂在 app 实例上)。
  2. 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 返回字段:

字段类型说明
idstringBucket ID
namestringBucket 名称
owner_idstring | null创建者用户 ID;可能为空
publicboolean是否为公开 Bucket
type'STANDARD'Bucket 类型
file_size_limitnumber | null文件大小限制,单位为字节;null 表示不限制
allowed_mime_typesstring[] | null允许上传的 MIME 类型列表;null 表示不限制
created_atstring创建时间,ISO 8601 日期时间字符串
updated_atstring更新时间,ISO 8601 日期时间字符串

Bucket 列表参数:

参数类型说明
limitnumber返回数量限制
offsetnumber分页偏移量
sortColumn'id' | 'name' | 'created_at' | 'updated_at'排序字段
sortOrder'asc' | 'desc'排序方向
searchstring按关键词搜索 Bucket

Bucket 创建 / 更新参数:

参数类型createBucketupdateBucket说明
publicboolean✓✓是否公开,创建时默认 false
fileSizeLimitnumber | string | null✓✓文件大小限制;数字按字节处理,字符串支持如 100MB,null 表示不限制
allowedMimeTypesstring[] | 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 / searchBucket[]
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):

参数类型说明
limitnumber返回数量限制
offsetnumber分页偏移量
sortColumn'id' | 'name' | 'created_at' | 'updated_at'排序字段
sortOrder'asc' | 'desc'排序方向
searchstring搜索关键词

createBucket(bucketId, options) / updateBucket(bucketId, options):

参数类型创建更新说明
publicboolean✓✓是否公开,创建时默认 false
fileSizeLimitnumber | string | null✓✓文件大小限制;数字按字节处理,字符串支持如 100MB,null 表示不限制
allowedMimeTypesstring[] | null✓✓允许上传的 MIME 类型列表,null 表示不限制
type'STANDARD'✓—Bucket 类型,仅创建时可传

返回值

listBuckets() 与 getBucket() 返回 Bucket 或 Bucket[]:

字段类型说明
idstringBucket ID
namestringBucket 名称
owner_idstring | null创建者用户 ID;可能为空
publicboolean是否为公开 Bucket
type'STANDARD'Bucket 类型
file_size_limitnumber | null文件大小限制,单位为字节;null 表示不限制
allowed_mime_typesstring[] | null允许上传的 MIME 类型列表;null 表示不限制
created_atstring创建时间,ISO 8601 日期时间字符串
updated_atstring更新时间,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() 得 ReadableStreamBlob / 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:

参数类型说明
cacheControlstring缓存时间,单位为秒;默认 3600
contentTypestring文件 MIME 类型;非 Blob / File / FormData 时建议显式指定
upsertboolean是否允许覆盖同名对象;upload() 默认 false,update() 等同覆盖
metadataRecord<string, any>用户自定义元数据
headersRecord<string, string>额外请求头
duplexstring透传给底层 fetch 的 duplex 配置

下载选项 DownloadOptions:

参数类型说明
downloadstring | boolean触发浏览器下载;字符串值作为下载文件名
cacheNoncestring缓存失效 nonce,追加到请求 URL 以绕过 CDN 缓存

列表选项 ListOptions:

参数类型说明
limitnumber返回数量限制,后端最大值为 1000
cursorstring翻页游标,由上一页响应的 nextCursor 提供
withDelimiterboolean是否使用 / 作为分隔符区分文件夹
sortBy.column'name' | 'created_at' | 'updated_at'排序字段
sortBy.order'asc' | 'desc'排序方向

复制 / 移动选项 DestinationOptions:

参数类型说明
destinationBucketstring目标 Bucket ID,默认与源 Bucket 相同
upsertboolean允许覆盖目标位置已有对象;用于 copy()
copyMetadataboolean是否复制源对象元数据;用于 copy(),默认由后端决定
metadataRecord<string, any>copyMetadata=false 时合并到目标对象的用户元数据

签名 / 公开 URL 选项:

参数类型说明
downloadstring | boolean触发浏览器下载;字符串值作为下载文件名

请求控制参数 FetchParameters:

参数类型说明
signalAbortSignal请求取消信号
cacheRequestCache透传给底层 fetch 的缓存策略;部分运行时可能忽略

Object 返回值

UploadResult:

字段类型说明
idstring对象 UUID
pathstringBucket 内相对路径
fullPathstring对象完整路径 bucketId/objectName

ListObjectsResponse:

字段类型说明
foldersListObjectsEntry[]当前前缀下的文件夹条目
objectsListObjectsEntry[]当前前缀下的对象条目
hasNextboolean是否还有下一页
nextCursorstring下一页游标
nextCursorKeystring下一页起始 key

ListObjectsEntry:

字段类型说明
keystring | null对象完整 key;文件夹条目可能为空
namestring对象名或文件夹名
idstring | null对象 UUID;文件夹条目可能为空
updated_atstring | null更新时间
created_atstring | null创建时间
last_accessed_atstring | null最后访问时间
metadataRecord<string, any> | null对象元数据

ObjectInfo:

字段类型说明
idstring对象 UUID
namestringBucket 内相对路径
versionstring | null对象版本标识;可能为空
bucketIdstring所属 Bucket ID
sizenumber | null文件大小,单位为字节
contentTypestring | null文件 MIME 类型
cacheControlstring | null缓存控制信息
etagstring | null对象 ETag
metadataRecord<string, any>用户自定义元数据
lastModifiedstring | null最后修改时间
createdAtstring | null创建时间

FullObject:

字段类型说明
namestringBucket 内相对路径
bucket_idstring所属 Bucket ID
owner_idstring | null创建者用户 ID;可能为空
versionstring | null对象版本标识;可能为空
idstring | null对象 UUID;可能为空
updated_atstring | null更新时间
created_atstring | null创建时间
last_accessed_atstring | null最后访问时间
metadataRecord<string, any>系统或对象元数据
user_metadataRecord<string, any>用户自定义元数据

SignedUrlsResultItem:

字段类型说明
pathstring请求签名的对象路径
signedUrlstring | null签名下载 URL;生成失败时为 null
errorstring | null单项错误信息;成功时为 null

CreateSignedUploadUrlResult:

字段类型说明
signedUrlstring签名上传 URL
tokenstring签名上传 token
pathstringBucket 内相对路径

uploadToSignedUrl() 返回:

字段类型说明
pathstringBucket 内相对路径
fullPathstring对象完整路径 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)优先级更高,会覆盖同名头。

版本与发布记录

@cloudbase/storage 共发布 364 个版本,首次发布于 2020/04/29;过去 12 个月发布了 134 个版本。

版本发布日期距今
3.9.3latest2026/11/16今天
3.10.0-beta.22026/11/133 天前
3.10.0-beta.12026/11/106 天前
3.10.0-beta.02026/10/2918 天前
3.9.22026/10/2621 天前
3.9.2-beta.02026/10/2027 天前

其他发布通道:v1 → 1.3.5,v1beta → 1.8.4,next_2025 → 2.9.6,next → 3.3.9,v2 → 2.28.8,alpha → 3.8.3-alpha.0。

关于 @cloudbase/storage 的常见问题

@cloudbase/storage 是什么?

云库 js sdk 存储模块

如何安装 @cloudbase/storage?

在项目目录运行 npm install @cloudbase/storage,或使用 pnpm add / yarn add / bun add。

@cloudbase/storage 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@cloudbase/storage 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@cloudbase/storage 可以商用吗?

@cloudbase/storage 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@cloudbase/storage 的下载量有多少?

根据 npm 官方下载统计,@cloudbase/storage 在 2026/10/10 – 2026/11/08 这 30 天内被下载 12,852 次,日均约 428 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@cloudbase/storage 还在维护吗?

最新版本 3.9.3 发布于 2026/11/16(今天);至今共发布 364 个版本,其中过去 12 个月发布了 134 个;首次发布于 2020/04/29。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。