应用部署

v3.0.0+

tcb app 命令自 v3.0.0 起提供。

tcb app 命令用于部署和管理 CloudBase 云应用。每次部署会覆盖上一次，并保留历史部署记录（可通过 tcb app versions 查看）。

适用场景：有构建流程的前端项目

适合以下场景：

• 有安装依赖 + 构建步骤的前端项目（React / Vue / Next.js / Vite / Angular / Nuxt 等）
• 纯静态项目
• CI/CD 流水线中自动化部署

CLI 会自动完成：安装依赖 → 构建 → 上传产物 → 绑定路由，无需手动操作文件。每次部署会覆盖上一次，可通过 tcb app versions list 查看历史部署记录。

---

tcb app deploy

部署应用。CLI 会自动执行：安装依赖 → 构建 → 上传构建产物 → 绑定路由。

以下三种调用方式完全等价：

tcb app deploy [serviceName] [options]   # 完整命令
tcb deploy [serviceName] [options]       # 顶层别名
tcb [options]                            # 裸命令（不带任何子命令时自动路由到 app deploy）

参数

参数	说明	默认值
[serviceName]	应用名称（可选，不填则自动从 package.json 读取或交互输入）	—
-e, --env-id <envId>	目标环境 ID	—
--framework <type>	框架类型：react / vue / vite / next / nuxt / angular / static	—
--install-command <cmd>	安装命令（留空则跳过安装）	npm install
--build-command <cmd>	构建命令（留空则跳过构建，适合纯静态项目）	—
--output-dir <dir>	构建产物目录（默认 ./dist；无需构建时填 ./）	自动检测
--deploy-path <path>	静态托管挂载路径	/服务名
--cwd <path>	项目目录（相对路径）	当前目录
--ignore <patterns>	忽略文件模式，逗号分隔，追加到 app.ignore 之后	—
--enable-git-ignore	合并项目 .gitignore 规则（默认不合并）	关闭
-f, --force	应用名称已存在时跳过确认直接覆盖	—

忽略规则语法

--ignore 参数与 .gitignore 合并（--enable-git-ignore）均遵循 glob 通配语法：

语法	示例	说明
通配符	*.log	匹配文件名（* 不跨目录层级）
任意层级	**/temp	匹配任意层级的 temp
目录整棵	dist/	忽略 dist 目录及其全部内容
根锚定	/build	仅匹配上传根目录下的 build
相对路径	src/test	相对上传根目录的路径锚定
单字符/字符类	?.log、[ab].log	支持单字符通配与字符类

! 取反： 不支持。.gitignore 或 --ignore 中的取反规则（如 !important.log）不生效，执行时会提示一次并忽略该规则。

规则合并优先级：默认规则（node_modules、.git）> .gitignore（开启时）> app.ignore > --ignore，全部累加。

示例

# 部署 Vite 项目（在项目根目录执行）
tcb app deploy --framework vite -e my-env-id

# 使用顶层别名，效果完全相同
tcb deploy --framework vite -e my-env-id

# 裸命令：什么都不加，交互式引导部署
tcb

# 指定项目子目录（monorepo 场景）
tcb app deploy --cwd ./frontend -e my-env-id

# 部署 Next.js 项目，指定构建产物目录
tcb app deploy --framework next --output-dir .next -e my-env-id

# 纯静态项目（跳过构建步骤）
tcb app deploy --framework static --build-command "" --output-dir ./public -e my-env-id

# CI 场景：跳过确认，覆盖更新已有应用
tcb app deploy --framework react --force -e my-env-id

# 追加忽略规则（逗号分隔），追加到 app.ignore 之后
tcb app deploy --ignore "dist/test,.env.local"

# 合并项目 .gitignore 规则（默认不合并，需显式开启）
tcb app deploy --enable-git-ignore

# 同时使用：合并 .gitignore + 追加 CLI 忽略规则
tcb app deploy --enable-git-ignore --ignore "*.map"

通过 cloudbaserc.json 配置部署

除了通过 CLI 参数指定部署选项外，也可以在 cloudbaserc.json 中配置 app 字段，实现零命令行参数的部署体验。

配置文件结构：

{
  "version": "2.0",
  "envId": "my-env-id",
  "app": {
    "serviceName": "my-app",
    "root": "./packages/web",
    "framework": "react",
    "installCommand": "npm install",
    "buildCommand": "npm run build",
    "outputDir": "build",
    "deployPath": "/my-app",
    "envVariables": {
      "API_URL": "https://api.example.com"
    }
  }
}

配置字段：

字段	类型	必填	默认值	说明
serviceName	String	否	package.json 的 name 或目录名	云应用服务名称
root	String	否	当前目录	应用项目根目录（相对于 cloudbaserc.json 所在目录），用于 monorepo 场景指定子项目路径
framework	String	否	自动检测	前端框架类型，支持值：react、vue、vite、next、nuxt、angular、static
installCommand	String	否	npm install	安装依赖命令，空字符串表示跳过安装步骤
buildCommand	String	否	根据框架自动检测	构建命令，空字符串跳过构建步骤（适用于纯静态项目）
outputDir	String	否	./dist（无构建命令时为 ./）	构建产物输出目录
deployPath	String	否	/${serviceName}	部署路径（静态托管挂载路径），必须以 / 开头
envVariables	Object	否	—	环境变量（非敏感），键值对形式，在云端构建时注入
ignore	String/Array	否	—	打包上传时忽略的文件/目录 glob 模式。如需合并项目 .gitignore 的规则，执行 tcb app deploy --enable-git-ignore 显式开启（默认不合并）

优先级总则：显式指定 > 声明式配置 > 自动推断 > 交互询问

⚠️ 注意：部分参数有特殊规则（如 envVariables 无 CLI 参数，buildCommand 有框架默认值等），详见下表。

各参数的优先级顺序：

参数	优先级
serviceName	CLI 位置参数 > cloudbaserc.json 配置 > 交互式选择 > 自动推断（package.json 或目录名）
root	--cwd 选项 > cloudbaserc.json 配置 > 当前目录
framework	--framework 选项 > cloudbaserc.json 配置 > 自动检测（package.json 依赖） > 未指定
installCommand	--install-command 选项 > cloudbaserc.json 配置 > 自动推断（npm install 或空） > 交互输入
buildCommand	--build-command 选项 > cloudbaserc.json 配置 > 自动检测（框架默认值或 package.json scripts） > 交互输入 > 空字符串
outputDir	--output-dir 选项 > cloudbaserc.json 配置 > 自动检测（框架默认值） > 交互输入 > ./dist（有构建）或 ./（无构建）
deployPath	--deploy-path 选项 > cloudbaserc.json 配置 > 交互输入（默认 /{serviceName}）
envVariables	仅从 cloudbaserc.json 配置读取（无 CLI 参数）
ignore	默认规则（node_modules、.git）> .gitignore（--enable-git-ignore 时）> cloudbaserc.json 的 app.ignore > --ignore 选项，全部累加

特殊说明：

• --cwd 与 config.app.root 都用于指定项目工作目录，--cwd 优先级更高
• envVariables 无对应 CLI 参数，仅能通过 cloudbaserc.json 配置
• 当指定 --yes 或 --json 时，会跳过所有交互式输入，改用自动推断值
• 框架自动检测遵循优先级：Next.js > Nuxt > Angular > Vite > Vue CLI > React（CRA）> 静态 HTML

自动保存：首次部署成功后，若 cloudbaserc.json 中不存在 app 配置，CLI 会自动将本次部署参数写回配置文件，后续部署无需重复输入。

更多配置字段的详细说明，请参考 配置文件文档。

---

tcb app list

查看当前环境的应用列表。

tcb app list [options]

参数

参数	说明	默认值
-e, --env-id <envId>	环境 ID	—
-l, --limit <n>	返回数量	20
-o, --offset <n>	偏移量	0
--json	输出 JSON	—

示例

tcb app list -e my-env-id

---

tcb app info

查看指定应用的详情（状态、版本、访问域名等）。

tcb app info <serviceName> [options]

示例

tcb app info my-app -e my-env-id

# JSON 输出（适合脚本读取访问域名）
tcb app info my-app --json -e my-env-id

---

tcb app versions list

查看应用版本历史列表。

tcb app versions list <serviceName> [options]

参数

参数	说明	默认值
<serviceName>	应用名称（必填）	—
-l, --limit <n>	返回数量	20
-o, --offset <n>	偏移量	0
-e, --env-id <envId>	环境 ID	—

示例

tcb app versions list my-app -e my-env-id

---

tcb app versions detail

查看应用指定版本的详细信息，默认显示最新版本。

tcb app versions detail <serviceName> [options]

参数

参数	说明	默认值
<serviceName>	应用名称（必填）	—
--version-name <name>	版本名称（不填则查最新版本）	—
-e, --env-id <envId>	环境 ID	—

示例

# 查看最新版本详情
tcb app versions detail my-app -e my-env-id

# 查看指定版本详情
tcb app versions detail my-app --version-name my-app-001 --env-id env-xxx

---

tcb app delete

删除应用记录，不会删除底层应用资源文件。

tcb app delete <serviceName> [options]

参数

参数	说明	默认值
<serviceName>	应用名称（必填）	—
-e, --env-id <envId>	环境 ID	—
--dry-run	预览删除操作，不实际执行	—

示例

tcb app delete my-app -e my-env-id

# 预览删除（不实际执行）
tcb app delete my-app -e my-env-id --dry-run

注意

此操作会删除应用的所有版本和资源，不可恢复。项目资源文件需单独在静态托管桶中手动清除。