tcb hosting deploy

上传本地文件或目录到静态网站。不指定 localPath 时上传当前目录下的全部文件。

项目有构建流程时用应用部署，它会构建后再上传；这个命令只上传已生成的产物。

语法

tcb hosting deploy [localPath] [cloudPath] [options]

参数

参数	必填	说明	默认值
`<localPath>`	否	本地文件或目录，相对当前目录解析	当前目录
`<cloudPath>`	否	云端目标路径	根目录
`-e, --env-id <envId>`	是	环境 ID	—
`--ignore <patterns>`	否	忽略的文件模式，逗号分隔，仅目录部署生效	—
`--enable-git-ignore`	否	合并项目 `.gitignore` 规则	不合并
`--entry <files>`	否	入口文件，逗号分隔，相对上传目录。资源上传完成后最后上传	自动识别各级 `index.html`
`--verify`	否	发布后校验远端文件与本地产物一致	—
`--safe`	否	发布前备份远端，失败自动回滚	—
`--prune`	否	发布成功后清理远端冗余文件	—
`--concurrency <number>`	否	上传并发数，大文件或弱网调小	20
`--retry-count <number>`	否	上传失败重试次数	2
`--retry-interval <ms>`	否	重试间隔，单位毫秒	1000

--verify、--safe、--prune 的流程见一致性发布。忽略规则的语法与合并优先级同 tcb app deploy，见 app deploy 忽略规则。

示例

# 部署当前目录下的全部文件
cd docs
tcb hosting deploy -e envId

# 把本地 index.html 上传到云端根目录
tcb hosting deploy ./index.html -e envId

# 指定云端路径，上传到 static/index.js
tcb hosting deploy ./static/index.js static/index.js -e envId

# 目录部署时排除文件，并合并 .gitignore
tcb hosting deploy ./dist -e envId --ignore "*.map,.DS_Store" --enable-git-ignore

# 大文件或弱网：降低并发、增加重试
tcb hosting deploy ./dist --concurrency 5 --retry-count 3

一致性发布

目录部署时加 --verify、--safe、--prune 任一开关，上传即进入一致性发布流程：扫描本地文件生成清单 → 备份远端 → 上传 → 校验 → 清理远端冗余文件。后三步按开关执行。

参数	说明
`--verify`	发布后对比远端文件与本地，校验文件大小与 MD5
`--safe`	发布前把远端文件备份到 `.cloudbase-backup/<时间戳>/`，上传或校验失败自动回滚
`--prune`	发布成功后删除当前 `cloudPath` 下、本地清单中不存在的文件

--prune 会二次确认，追加 --yes 跳过。它只清理当前 cloudPath 前缀下的文件，建议与 --safe 一起用。

# 校验发布结果
tcb hosting deploy ./dist --verify

# 安全发布，失败自动回滚
tcb hosting deploy ./dist --safe

# 安全发布并清理远端冗余文件
tcb hosting deploy ./dist --safe --prune --yes

# 指定入口文件
tcb hosting deploy ./dist --entry index.html,admin/index.html

备份不会自动清理，确认发布无误后手动删除。

声明式部署

在 cloudbaserc.json 里配置 hosting 字段，用 tcb deploy 一次部署多个站点。自 CLI v3.8.2 起构建与部署分离：

构建：执行 tcb app build，在本地运行 buildCommand 生成产物，不安装依赖、不上传
部署：执行 tcb deploy，上传产物并编排其余资源

配置了 buildCommand 时，tcb deploy 不再执行本地构建。产物目录不存在会报错并提示先运行 tcb app build。没有 buildCommand 的纯静态站点直接上传 outputDir。

字段	类型	必填	默认值	说明
`name`	String	是	—	应用名称，同一配置文件内唯一，被 `gateway.routes[].target: hosting:<name>` 引用
`root`	String	否	`.`	应用根目录，相对 `cloudbaserc.json` 所在目录，用于 monorepo
`framework`	String	否	`static`	`react`、`vue`、`vite`、`vite-react`、`vite-vue`、`next`、`nuxt`、`angular`、`static`、`custom`。未配置时读 `root/package.json` 检测；`static` 与 `custom` 表示纯静态，不构建
`installCommand`	String	否	—	安装命令，CLI 不再本地执行，需自行安装依赖
`buildCommand`	String	否	—	构建命令。非空时先用 `tcb app build` 本地构建；为空且检测不到框架时按纯静态上传 `outputDir`
`outputDir`	String	否	`dist`	构建产物目录，相对 `root`。纯静态时默认 `root`
`deployPath`	String	否	`/`	部署路径前缀，多个站点用不同路径。缺前导 `/` 会自动补全并在终端提示
`envVariables`	Object	否	—	构建时注入 `process.env` 的变量，非敏感信息
`ignore`	String / Array	否	—	上传时忽略的文件 glob 模式，如 `["node_modules", "*.log"]`

framework 取 vite、vite-react、vite-vue 时默认构建命令为 npm run build、产物目录为 dist。

{
  "hosting": [
    {
      "name": "web",
      "root": "./packages/web",
      "framework": "vite",
      "buildCommand": "npm run build",
      "outputDir": "dist",
      "deployPath": "/web"
    }
  ]
}

注意：

deployPath 含空白、shell 特殊字符、../，或以 - 开头时会被拒绝
多个站点的 deployPath 不能重复，且要与 gateway.routes[].path 对应
envVariables 注入构建过程，不是运行时环境变量

路径与限制

路径格式

localPath：本地路径，用系统分隔符。Windows 下是 \，如 .\static\index.js
cloudPath：云端相对根目录的路径，统一用 /，如 static/css/index.css

服务开通

静态网站服务需先开通。平台版账号创建环境时自动分配托管资源，普通账号需手动开通。

未开通时，tcb hosting 的各条命令只查询状态、不会代为开通，会直接报错。运行 tcb hosting detail 按提示开通，或在云开发控制台开通。

服务刚开通时状态为“初始化中”，上传会被拒绝。命令每 5 秒轮询、最长等待约 6 分钟，超时后重新执行即可。

上传限制

单个文件上限 50 TB，文件数量不限
上传默认失败重试 2 次，瞬时 socket hang up 会自动恢复
弱网或大文件场景调低 --concurrency（默认 20），或增加 --retry-count（默认 2）、--retry-interval（默认 1000 毫秒）
仍不稳定时可设置 COS_SDK_KEEPALIVE=false 关闭 SDK 长连接

其他

Vue Router 的 history 模式需在静态网站控制台把错误页面配置为入口页 index.html
默认访问域名在控制台查看，自定义域名需完成 ICP 备案

语法​

参数​

示例​

一致性发布​

声明式部署​

路径与限制​

路径格式​

服务开通​

上传限制​

其他​

语法

参数

示例