# @cloudbase/storage 中文文档

规范地址：https://npmcn.com/package/%40cloudbase/storage/

版本：3\.9\.3
npm 元数据更新时间：2026-11-16T10:13:49.868Z
中文译文更新时间：2026-11-16T10:14:09.496Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cloudbase/storage
原文对照：https://npmcn.com/package/%40cloudbase/storage/?lang=original
项目主页：https://github.com/TencentCloudBase/cloudbase-js-sdk#readme
源码仓库：https://github.com/TencentCloudBase/cloudbase-js-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.4 MB，97 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2020-04-29T02:28:27.776Z
- 最新版本发布：2026-11-16T10:13:49.661Z
- 近 30 天下载量：12852（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：364（近 12 个月 134 个）

## 中文简介

云库 js sdk 存储模块

## 安装

```sh
npm install @cloudbase/storage
```

也可以使用：`pnpm add @cloudbase/storage`、`yarn add @cloudbase/storage`、`bun add @cloudbase/storage`

## README

# @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 结构

```txt
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 类型，仅创建时可传 |

示例：

```ts
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()` 分流到两个对等且独立的对象操作客户端：**

```ts
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` 资源：

```ts
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 }`：

```ts
const { data, error } = await storage.getBucket('avatars')

if (error) {
  console.error(error.message)
  return
}

console.log(data.name)
```

也可以使用 `throwOnError()`，开启后失败会抛异常，成功仍返回 `{ data, error: null }`：

```ts
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`。

快速示例：

```ts
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'])
```

复制 / 移动：

```ts
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：

```ts
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`）优先级更高，会覆盖同名头。

## 常见问题

### @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 和提交记录判断。

