tcb app deploy

部署单个静态托管应用，自动完成 安装依赖 → 构建 → 上传产物 → 绑定路由，并覆盖上一次的部署。

适用场景

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

语法

tcb app deploy [serviceName] [options]

参数

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

示例

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

# 交互式引导部署（不确定参数时）
tcb app deploy

# 指定项目目录（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"

忽略规则语法

--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，全部累加。

通过 cloudbaserc.json 配置

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

配置文件结构：

{
  "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	否	项目目录	应用根目录（相对项目目录），用于 monorepo 场景指定子项目路径
`framework`	String	否	自动检测	前端框架类型，支持值：`react`、`vue`、`vite`、`next`、`nuxt`、`angular`、`static`
`installCommand`	String	否	`npm install`	安装依赖命令，空字符串表示跳过安装步骤。`tcb deploy` 下被忽略（该命令不构建）
`buildCommand`	String	否	根据框架自动检测	构建命令，空字符串跳过构建步骤（适用于纯静态项目）。`tcb deploy` 下被忽略，请改用 `tcb app build` 本地构建
`outputDir`	String	否	`./dist`（无构建命令时为 `./`）	构建产物输出目录。`tcb deploy` 不构建，只用它确定上传目录：未配置时按 `buildCommand` / `framework` / `package.json` 推断（纯静态回退项目根并在终端提示），推断结果见声明式部署 FAQ；产物目录不存在或为空报 `BUILD_OUTPUT_NOT_FOUND`
`deployPath`	String	否	`/${serviceName}`	部署路径（静态托管挂载路径）。缺前导 `/` 会自动补全（`web` → `/web`）并在终端提示；含空白或 shell 特殊字符（分号、管道、重定向符、`$`、反引号、通配符等）、含 `../`、以 `-` 开头则报 `INVALID_PARAM`
`envVariables`	Object	否	—	环境变量（非敏感），键值对形式，在云端构建时注入
`ignore`	String/Array	否	—	打包上传时忽略的文件/目录 glob 模式，合并顺序见忽略规则语法

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

各参数的优先级顺序：

参数	优先级
`serviceName`	CLI 位置参数 > `cloudbaserc.json` 配置 > 交互式选择 > 自动推断（package.json 或目录名）
`root`	`cloudbaserc.json` 的 `app.root` > 项目目录（由 `--cwd` 决定）
`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 apps/shop 配合 app.root: ./frontend，应用目录为 apps/shop/frontend，详见全局选项
指定 --yes 或 --json 时跳过所有交互式输入，改用自动推断值
框架自动检测遵循优先级：Next.js > Nuxt > Angular > Vite > Vue CLI > React（CRA）> 静态 HTML

自动保存：首次部署成功后，若项目目录下的 cloudbaserc.json 中不存在 app 配置，CLI 会把本次部署参数写回该文件，后续部署无需重复输入。root 记为相对项目目录的子路径；应用目录等于项目目录时不写该字段。deployPath 记为补全后的绝对路径（--deploy-path web 写回为 /web），等于默认值 /{serviceName} 时不写该字段。

字段的完整说明见配置文件。

注意事项

tcb app 命令自 v3.0.0 起提供。自 v3.9.0 起的版本变化：

tcb deploy 不再是本命令的别名 —— tcb deploy <serviceName> 与 --framework、--build-command、--output-dir 等 8 个 app 专属选项报 INVALID_PARAM，改用 tcb app deploy，详见声明式部署 · 注意事项
tcb app build 同时构建 app 与 hosting[] —— 此前只构建 hosting[]

应用列表：部署后用 tcb app list 确认结果
应用详情：查看访问域名
版本列表：查看每次部署生成的版本
构建应用：只在本地构建，不上传

语法​

参数​

示例​

忽略规则语法​

通过 cloudbaserc.json 配置​

注意事项​

相关命令​

语法

参数

示例

忽略规则语法

通过 cloudbaserc.json 配置

注意事项

相关命令