云存储

云存储是云开发为用户提供的文件存储能力，用户可以通过云开发提供的 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）