跳到主要内容

云存储

云存储是云开发为用户提供的文件存储能力，用户可以通过云开发提供的 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:uploadtcb storage upload
tcb storage:downloadtcb storage download
tcb storage:deletetcb storage rm
tcb storage:listtcb storage list
tcb storage:urltcb storage url
tcb storage:detailtcb storage detail
tcb storage:get-acltcb permission
tcb storage:set-acltcb 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 头
--upsertPOST 模式下允许覆盖已存在对象
--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。