云存储

云存储是云开发为用户提供的文件存储能力，用户可以通过云开发提供的 CLI 工具、SDK 对存储进行操作，如上传、下载文件。存储在云存储中的文件默认提供 CDN 加速访问，用户可以快速访问云存储中的文件。

路径说明

localPath 为本地文件或文件夹的路径，为 目录/文件名 的形式，如 ./index.js、static/css/index.css 等。
cloudPath 为云存储文件或文件夹的相对根目录的路径，为 目录/文件名 的形式，如 index.js、static/css/index.js 等。

⚠️ 注意事项

Windows 系统中 localPath 为本地路径形式，是系统可以识别的路径，通常使用 \ 分隔符。cloudPath 是云端文件路径，均需要使用 / 分隔符。

上传文件

您可以使用下面的命令上传文件/文件夹，当 CLI 检测到 localPath 为文件夹时，会自动上传文件内的所有文件。

tcb storage upload localPath cloudPath

# 指定上传重试次数（0-10，默认 1）
tcb storage upload localPath cloudPath --times 3

# 指定重试间隔（ms，默认 500）
tcb storage upload localPath cloudPath --interval 1000

下载文件

您可以使用下面的命令下载文件/文件夹，需要下载文件夹时，需要指定 --dir 参数。

# 下载文件
tcb storage download cloudPath localPath

# 下载文件夹
tcb storage download cloudPath localPath --dir

下载全部文件

当指定 cloudPath 为 / 时，即代表下载云存储中的全部文件：

tcb storage download / localPath --dir

删除文件

版本提示

tcb storage rm 命令自 v3.0.0 起新增，是推荐的删除命令，功能更强大。

命令变更

旧命令 tcb storage delete 已废弃，保留向后兼容，请使用新命令 tcb storage rm。

# 删除单个文件
tcb storage rm cloudPath

# 删除文件夹（递归删除）
tcb storage rm cloudPath --dir

# 强制删除，不提示确认
tcb storage rm cloudPath --force

# 模拟运行，只显示将要删除的文件，不实际执行
tcb storage rm cloudPath --dry-run

命令参数：

参数	说明
`--dir`	删除目标是文件夹（递归删除）
`--recursive`	同 `--dir`
`--force`	强制删除，不提示确认
`--dry-run`	模拟运行，只显示将要删除的文件，不实际删除

列出文件列表

列出文件夹下的文件：

tcb storage list [cloudPath]

复制/移动文件

版本提示

自 v3.0.0 起新增此功能。

在云端复制或移动文件（仅支持文件级别，不支持文件夹）：

# 复制文件
tcb storage cp <sourcePath> <destPath>

# 移动文件（复制后删除源文件）
tcb storage cp <sourcePath> <destPath> --move

# 强制覆盖已存在的目标文件
tcb storage cp <sourcePath> <destPath> --force

# 跳过已存在的目标文件
tcb storage cp <sourcePath> <destPath> --skip

命令参数：

参数	说明
`--move`	移动文件（复制后删除源文件）
`--force`	强制覆盖已存在的文件
`--skip`	跳过已存在的文件
`-e, --env-id <envId>`	环境 ID

搜索文件

版本提示

自 v3.0.0 起新增此功能。

按文件名模式搜索云端文件：

# 基本搜索（支持通配符，如 *.jpg）
tcb storage search <pattern>

# 在指定目录下搜索
tcb storage search <pattern> --dir images/

# 按文件类型过滤（如 jpg、png、pdf）
tcb storage search <pattern> --type jpg

# 将 pattern 作为正则表达式处理
tcb storage search <pattern> --regex

命令参数：

参数	说明
`-e, --env-id <envId>`	环境 ID
`--dir <dir>`	指定搜索目录（不指定则搜索根目录）
`--type <ext>`	按文件类型过滤（如 `jpg`、`png`、`pdf`）
`--regex`	将 pattern 作为正则表达式处理

获取文件访问链接

获取文件的临时访问链接：

tcb storage url cloudPath

# 指定链接有效期（秒，默认 3600）
tcb storage url cloudPath --expire 7200

获取文件信息

获取文件的简单信息：

tcb storage detail cloudPath

权限管理

已废弃（v3.0.0+）

tcb storage get-acl、tcb storage set-acl、tcb storage rules get、tcb storage rules update 等存储权限命令自 v3.0.0 起已废弃。

请迁移到 tcb permission 命令进行资源权限管理，详见权限管理。

获取访问权限

tcb storage get-acl

设置访问权限

tcb storage set-acl --acl <权限值>

可选权限值：READONLY、PRIVATE、ADMINWRITE、ADMINONLY

获取权限规则

tcb storage rules get

更新权限规则

# 使用预设权限
tcb storage rules update --acl READONLY

# 使用自定义规则（JSON 格式）
tcb storage rules update --acl CUSTOM --rules '[{"role":"anyone","action":"read"}]'

可选权限值：READONLY、PRIVATE、ADMINWRITE、ADMINONLY、CUSTOM（自定义规则时使用）

废弃命令说明

以下旧格式命令（冒号分隔）已废弃，保留向后兼容，请迁移到新命令：

旧命令	新命令
`tcb storage:upload`	`tcb storage upload`
`tcb storage:download`	`tcb storage download`
`tcb storage:delete`	`tcb storage rm`
`tcb storage:list`	`tcb storage list`
`tcb storage:url`	`tcb storage url`
`tcb storage:detail`	`tcb storage detail`
`tcb storage:get-acl`	`tcb permission`
`tcb storage:set-acl`	`tcb permission`

命令速查

命令	说明
`tcb storage upload <local> <cloud>`	上传文件/文件夹
`tcb storage download <cloud> <local>`	下载文件/文件夹
`tcb storage rm <path>`	删除文件/文件夹（推荐）
`tcb storage list [path]`	列出文件列表
`tcb storage cp <src> <dest>`	复制/移动文件
`tcb storage search <pattern>`	搜索文件
`tcb storage url <path>`	获取临时访问链接
`tcb storage detail <path>`	获取文件信息
`tcb storage get-acl`	获取访问权限（已废弃，使用 `tcb permission`）
`tcb storage set-acl`	设置访问权限（已废弃，使用 `tcb permission`）
`tcb storage rules get`	获取权限规则（已废弃，使用 `tcb permission`）
`tcb storage rules update`	更新权限规则（已废弃，使用 `tcb permission`）

PostgreSQL 环境

版本提示

以下命令面向 PostgreSQL 架构 的云开发环境，自 @cloudbase/cli@3.4.0 起提供。

这些命令对应 SDK 的 PG Storage HTTP API（参见 cloudbase-manager-node PG 接口）。
在 PG 环境下，本页前面的传统 tcb storage 平铺命令（upload / download / delete / rm / list / url / detail / cp / search 等）会被拒绝执行，CLI 会在提示中给出对应的 PG 子命令替代项。
创建 PG 环境可使用：tcb env create --alias <name> --package <pkg> --postgresql --yes。
查询某个环境是否为 PG 环境，可运行 tcb env list 查看类型。

命令分组速览

命令组	功能
`tcb storage buckets`	管理 Storage bucket（PG 元信息）
`tcb storage policies`	查看 storage schema 下的 RLS 策略
`tcb storage objects`	对象 CRUD、签名、复制、移动等

PG 环境下，tcb db execute 也支持执行 PostgreSQL SQL，包括 bucket / 策略管理 SQL（详见关系型数据库（MySQL）中的 PostgreSQL 扩展说明）。

`tcb storage buckets list`

列出当前 PG 环境下所有 Storage bucket。

tcb storage buckets list [-e <envId>] [--json]

--json：输出原始 PGExecuteResult（含 Columns / Rows）。
表格输出列：Id / Name / Public / Size Limit / MIME Types / Created / Updated。

Bucket 操作通过 tcb db execute 执行 SQL 完成，例如：

# 创建 bucket
tcb db execute -e <envId> --sql "INSERT INTO storage.buckets (id, name, public, created_at, updated_at) VALUES ('avatars', 'avatars', false, now(), now())"

`tcb storage policies list`

列出 storage schema 下 buckets / objects 表上的 RLS 策略。

tcb storage policies list [--table buckets|objects] [-e <envId>] [--json]

参数	说明
`--table <table>`	按表过滤，可选 `buckets` / `objects`；不传则同时返回两表的策略
`--json`	输出原始 `PGExecuteResult`

RLS 策略变更通过 tcb db execute --role postgres 执行 CREATE POLICY / DROP POLICY。

`tcb storage objects upload`

上传本地文件到 Storage bucket。

tcb storage objects upload <localPath> <key> -b <bucketId> [options]

参数	说明
`<localPath>`	本地文件绝对/相对路径，必须是文件
`<key>`	远端对象名（不能以 `/` 开头）
`-b, --bucket <bucketId>`	Bucket ID，可用环境变量 `TCB_BUCKET_ID` 替代
`--content-type <mime>`	显式 MIME，不传则按 `扩展名 → magic bytes` 推断
`--cache-control <value>`	整数自动转 `max-age=<n>`，字符串原样作为 `Cache-Control`
`--metadata <json>`	自定义 metadata JSON，内部 Base64 编码到 `X-Metadata`
`--robots-tag <value>`	`X-Robots-Tag` 头
`--upsert`	POST 模式下允许覆盖已存在对象
`--use-put`	使用 PUT 方法（始终覆盖）
`--json`	输出 SDK 原始返回（`{ Id, Key }`）

示例：

tcb storage objects upload ./hello.txt test/hello.txt -b my-bucket
tcb storage objects upload ./hello.txt test/hello.txt -b my-bucket --content-type text/plain --upsert

`tcb storage objects download`

从 Storage bucket 下载对象到本地。

tcb storage objects download <key> [localPath] -b <bucketId> [options]

参数	说明
`<key>`	对象名
`[localPath]`	本地路径；省略时输出到 stdout；指向已存在目录会自动拼上 `key` 的 basename
`-b, --bucket <bucketId>`	Bucket ID
`-m, --method <method>`	`GET`（默认）/ `HEAD`
`--download <filename>`	触发浏览器下载（`?download=<filename>`）
`--if-none-match <etag>`	`If-None-Match` 头（仅认证下载路径生效）
`--if-modified-since <date>`	`If-Modified-Since` 头
`--range <range>`	`Range` 头（断点续传）
`--overwrite`	当 `localPath` 已存在时允许覆盖
`--json`	仅返回元信息（`{ status, headers }`），不落盘

行为说明：

已登录 → 走认证下载路径（downloadAuthenticatedObject），可访问 private/public bucket；
未登录 → 回退到 downloadPublicObject，仅能访问 public bucket；
--method HEAD 或 --json 模式下不会写本地文件。

`tcb storage objects stat`

查询对象元信息。

tcb storage objects stat <key> -b <bucketId> [options]

参数	说明
`-m, --method <method>`	`GET`（默认）/ `HEAD`，HEAD 仅认证路径支持
`--json`	输出 `{ status, headers, body }`，`body` 即 `IObjectInfoHttpPayload`

表格输出按以下字段顺序展示：id / name / bucket_id / version / size / content_type / cache_control / etag / last_modified / created_at / metadata。

`tcb storage objects list`

列出 bucket 中的对象，支持前缀过滤、分页与排序。

tcb storage objects list -b <bucketId> [options]

参数	说明
`--prefix <prefix>`	路径前缀过滤
`--limit <n>`	分页大小，1~1000，默认 20，超出范围会以 `INVALID_PARAM`（exit 3）拒绝
`--cursor <cursor>`	翻页游标（上一次响应的 `nextCursor`）
`--with-delimiter`	使用 `/` 分隔文件夹
`--sort-by <column>`	排序列，可选 `name` / `created_at` / `updated_at`
`--sort-order <order>`	排序方向，可选 `asc`（默认）/ `desc`
`--json`	输出 SDK 原始返回（含 `folders` / `objects` / `hasNext` / `nextCursor`）

list 接口需要登录态，未登录时会以 AUTH_FAILED 失败。

`tcb storage objects rm`

删除对象，单次最多 20 个。

tcb storage objects rm <keys...> -b <bucketId> [-y] [--json]

参数	说明
`<keys...>`	1~20 个对象名；超过 20 个会以 `INVALID_PARAM`（exit 3）拒绝
`-y, --yes`	跳过删除前的确认提示
`--json`	单 key 走 `deleteObject`，输出 `{ message }`；多 key 走 `deleteObjects`，输出 `IDeletedObjectInfo[]`

表格输出列：Key / Status，Status 为 DELETED / NOT_FOUND（批量删除中不存在的对象会被服务端静默跳过）。

`tcb storage objects cp`

复制对象到新位置。

tcb storage objects cp <srcKey> <dstKey> -b <bucketId> [options]

参数	说明
`-b, --bucket <bucketId>`	源 Bucket ID
`--dst-bucket <bucketId>`	目标 Bucket ID，默认与源 Bucket 相同
`--copy-metadata <bool>`	是否复制源对象 metadata，默认 `true`；`false` 时 `--metadata` / `--user-metadata` 才生效
`--metadata <json>`	系统 metadata JSON，与源 metadata 合并；COS 仅识别 `cacheControl` / `mimetype` / `contentType`
`--user-metadata <json>`	用户自定义 metadata JSON，整体替换目标 user_metadata
`--upsert`	允许覆盖目标位置已有对象
`--json`	输出 SDK 原始返回（`ICopyObjectHttpResult`）

校验细节：

同 bucket 下源 key 与目标 key 相同且未传 --upsert → INVALID_PARAM；
--metadata / --user-metadata 仅在 --copy-metadata false 时生效，其他情况下传入会被 CLI 直接拒绝。

`tcb storage objects mv`

移动（rename）对象到新位置；服务端一次性完成「复制 + 删除源对象」。

tcb storage objects mv <srcKey> <dstKey> -b <bucketId> [--dst-bucket <bucketId>] [--json]

同 bucket 下源 key 与目标 key 完全相同会被本地拦截为 INVALID_PARAM。

`tcb storage objects sign`

为对象生成签名 URL，默认下载签名，加 --upload 切换为上传签名。

# 下载签名
tcb storage objects sign <keys...> -b <bucketId> [--expires-in <seconds>] [--json]

# 上传签名
tcb storage objects sign <key> --upload -b <bucketId> [--upsert] [--json]

参数	说明
`<keys...>`	下载模式 1~500 个；上传模式仅允许 1 个
`--upload`	切换到上传签名模式
`--expires-in <seconds>`	过期时间（秒），>= 1，默认 600；仅下载模式
`--upsert`	允许覆盖（`x-upsert: true`），仅上传模式
`--json`	下载模式输出 `[{ path, signedURL, error }]`；上传模式输出 `{ url, token }`

互斥校验：

--upload 与 --expires-in 互斥；
下载模式下传 --upsert 会被拒绝；
--upload 一次只能签 1 个 key。

退出码

退出码	含义
`3 INVALID_INPUT`	包含 `INVALID_PARAM` / `MISSING_PARAM` / `FLAT_CMD_NOT_AVAILABLE_IN_PG` / `ENV_NOT_PG` 等

详见 exit-codes。

路径说明​

上传文件​

下载文件​

下载全部文件​

删除文件​

列出文件列表​

复制/移动文件​

搜索文件​

获取文件访问链接​

获取文件信息​

权限管理​

获取访问权限​

设置访问权限​

获取权限规则​

更新权限规则​

废弃命令说明​

命令速查​

PostgreSQL 环境​

命令分组速览​

tcb storage buckets list​

tcb storage policies list​

tcb storage objects upload​

tcb storage objects download​

tcb storage objects stat​

tcb storage objects list​

tcb storage objects rm​

tcb storage objects cp​

tcb storage objects mv​

tcb storage objects sign​

退出码​

路径说明

上传文件

下载文件

下载全部文件

删除文件

列出文件列表

复制/移动文件

搜索文件

获取文件访问链接

获取文件信息

权限管理

获取访问权限

设置访问权限

获取权限规则

更新权限规则

废弃命令说明

命令速查

PostgreSQL 环境

命令分组速览

`tcb storage buckets list`

`tcb storage policies list`

`tcb storage objects upload`

`tcb storage objects download`

`tcb storage objects stat`

`tcb storage objects list`

`tcb storage objects rm`

`tcb storage objects cp`

`tcb storage objects mv`

`tcb storage objects sign`

退出码