应用部署

版本提示

自 v5.0.0 起新增此模块。

CloudAppService 提供 Web 应用的部署管理能力，通过 app.cloudAppService 访问。

与 CloudRun 的区别

app.cloudAppService（本文档）：CloudApp 应用部署，目前支持 static-hosting（静态托管）部署类型，提供完整的应用版本管理。
app.cloudBaseRun（旧称 app.cloudApp，已弃用别名）：云托管（CloudBaseRun / TCBR），用于容器化服务部署。两者是独立的服务，请勿混淆。

命名迁移说明

在 v5.0.0 之前，app.cloudApp 是 CloudBaseRunService（云托管）的访问入口。

从 v5.0.0 起：

app.cloudApp —— 已废弃，仍可访问 CloudBaseRunService，但建议迁移到 app.cloudBaseRun
app.cloudAppService —— 新入口，访问 CloudApp 应用部署服务

createApp

1. 接口描述

接口功能：创建或更新 CloudApp 应用（首次调用创建，同名应用再次调用触发更新部署）

接口声明：app.cloudAppService.createApp(params): Promise<ICreateCloudAppResult>

2. 输入参数

字段	必填	类型	说明
deployType	是	`DeployType`	部署类型：`static-hosting`（静态托管）/ `http-function`（预留）
serviceName	是	String	应用服务名称，全局唯一
envId	否	String	环境 ID，默认取初始化时的 envId
buildType	否	`BuildType`	构建类型：`GIT` / `ZIP`（默认） / `TEMPLATE`
staticConfig	否	`IStaticConfig`	静态托管配置（deployType 为 static-hosting 时使用）

IStaticConfig

字段	必填	类型	说明
cosTimestamp	是	String/Number	COS 上传时间戳（由 `uploadCode` 返回）
framework	否	String	框架类型：`vue`、`react`、`next`、`nuxt`、`vite`、`angular`、`static`
nodeJsVersion	否	String	Node.js 版本，默认 `20`
appPath	否	String	访问路径（hosting mount path），默认 `/serviceName`
buildPath	否	String	构建产物目录
staticCmd	否	`IStaticCmd`	构建命令配置
staticEnv	否	`IStaticEnv`	静态环境变量

IStaticCmd

字段	说明
buildCmd	构建命令（如 `npm run build`）
installCmd	安装命令（如 `npm install`）
deployCmd	部署命令（通常自动生成，无需手动指定）

3. 返回结果

字段	类型	说明
ServiceName	String	应用服务名称
BuildId	String	构建 ID，用于轮询状态
RequestId	String	请求唯一标识

describeAppList

1. 接口描述

接口功能：查询 CloudApp 应用列表

接口声明：app.cloudAppService.describeAppList(params): Promise<IDescribeCloudAppListResult>

2. 输入参数

字段	必填	类型	说明
deployType	是	`DeployType`	部署类型：`static-hosting` 等
envId	否	String	环境 ID
pageNo	否	Number	页码（从 1 开始）
pageSize	否	Number	每页大小
searchKey	否	String	按应用名模糊搜索

3. 返回结果

字段	类型	说明
Total	Number	应用总数
ServiceList	`CloudAppServiceItem[]`	应用列表
RequestId	String	请求唯一标识

CloudAppServiceItem

字段	类型	说明
ServiceName	String	应用服务名称
DeployType	String	部署类型
Framework	String	框架类型
Domain	String	访问域名
AppPath	String	访问路径
CreateTime	String	创建时间
LatestVersionName	String	最新版本名
LatestStatus	String	最新版本状态：`BUILDING` / `SUCCESS` / `FAILED`
LatestBuildTime	String	最新构建时间

describeAppInfo

1. 接口描述

接口功能：查询单个 CloudApp 应用详情

接口声明：app.cloudAppService.describeAppInfo(params): Promise<IDescribeCloudAppInfoResult>

2. 输入参数

字段	必填	类型	说明
deployType	是	`DeployType`	部署类型
serviceName	是	String	应用服务名称
envId	否	String	环境 ID

3. 返回结果

字段	类型	说明
ServiceName	String	应用服务名称
DeployType	String	部署类型
Framework	String	框架类型
Domain	String	访问域名
AppPath	String	访问路径
CreateTime	String	创建时间
LatestVersionName	String	最新版本名
LatestStatus	String	最新版本状态
LatestBuildTime	String	最新构建时间

deleteApp

1. 接口描述

接口功能：删除 CloudApp 应用（包括全部历史版本）

接口声明：app.cloudAppService.deleteApp(params): Promise<IDeleteCloudAppResult>

2. 输入参数

字段	必填	类型	说明
deployType	是	`DeployType`	部署类型
serviceName	是	String	应用服务名称
envId	否	String	环境 ID

3. 返回结果

字段	类型	说明
Result	Boolean	是否删除成功
RequestId	String	请求唯一标识

describeAppVersion

1. 接口描述

接口功能：查询应用指定版本详情（包含构建状态）

接口声明：app.cloudAppService.describeAppVersion(params): Promise<IDescribeCloudAppVersionResult>

2. 输入参数

字段	必填	类型	说明
deployType	是	`DeployType`	部署类型
serviceName	是	String	应用服务名称
envId	否	String	环境 ID
versionName	否	String	版本名称（与 buildId 二选一）
buildId	否	String	构建 ID（与 versionName 二选一）

3. 返回结果

字段	类型	说明
BuildType	String	构建类型
BuildId	String	构建 ID
Status	String	构建状态：`BUILDING` / `SUCCESS` / `FAILED` / `PENDING`
Domain	String	版本访问域名（SUCCESS 时有值）
Url	String	版本访问 URL（SUCCESS 时有值）
BuildDuration	Number	构建耗时（秒）
FailReason	String	失败原因（FAILED 时有值）

describeAppVersionList

1. 接口描述

接口功能：查询应用的版本列表

接口声明：app.cloudAppService.describeAppVersionList(params): Promise<IDescribeCloudAppVersionListResult>

2. 输入参数

字段	必填	类型	说明
deployType	是	`DeployType`	部署类型
serviceName	是	String	应用服务名称
envId	否	String	环境 ID
pageNo	否	Number	页码
pageSize	否	Number	每页大小

3. 返回结果

字段	类型	说明
Total	Number	版本总数
VersionList	`CloudAppVersion[]`	版本列表
RequestId	String	请求唯一标识

deleteAppVersion

1. 接口描述

接口功能：删除应用的指定历史版本

接口声明：app.cloudAppService.deleteAppVersion(params): Promise<Object>

2. 输入参数

字段	必填	类型	说明
deployType	是	`DeployType`	部署类型
serviceName	是	String	应用服务名称
versionName	是	String	要删除的版本名
envId	否	String	环境 ID

代码上传

uploadCode

1. 接口描述

接口功能：将本地代码压缩后上传到 COS，用于后续 createApp 部署。

接口声明：app.cloudAppService.uploadCode(params): Promise<IUploadCloudAppCodeResult>

提示

通常情况下，CLI（tcb app deploy）会自动调用此接口完成代码上传，无需手动调用。直接使用 SDK 进行自动化部署时才需要手动调用。

2. 输入参数

字段	必填	类型	说明
envId	否	String	环境 ID
serviceName	是	String	应用服务名称
filePath	是	String	要上传的文件或目录的本地绝对路径
ignore	否	`string[]`	上传时忽略的文件/目录 glob 模式
onProgress	否	Function	上传进度回调 `(data: IProgressData) => void`

3. 返回结果

字段	类型	说明
cosTimestamp	String	COS 上传时间戳，需传入 `createApp` 的 `staticConfig.cosTimestamp`
RequestId	String	请求唯一标识

完整使用示例

import CloudBase from '@cloudbase/manager-node'
import path from 'path'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function deployApp() {
  const serviceName = 'my-react-app'

  // 1. 上传代码
  console.log('上传代码...')
  const { cosTimestamp } = await app.cloudAppService.uploadCode({
    serviceName,
    filePath: path.resolve('./my-react-app'),
    ignore: ['**/node_modules/**', '**/.git/**']
  })

  // 2. 创建/更新应用
  console.log('触发部署...')
  const { BuildId } = await app.cloudAppService.createApp({
    deployType: 'static-hosting',
    serviceName,
    buildType: 'ZIP',
    staticConfig: {
      framework: 'react',
      cosTimestamp,
      appPath: `/${serviceName}`,
      buildPath: 'build',
      staticCmd: {
        buildCmd: 'npm run build',
        installCmd: 'npm install'
      }
    }
  })

  // 3. 轮询构建状态
  console.log('等待构建完成，BuildId:', BuildId)
  let status = 'BUILDING'
  while (status === 'BUILDING' || status === 'PENDING') {
    await new Promise(r => setTimeout(r, 5000))
    const version = await app.cloudAppService.describeAppVersion({
      deployType: 'static-hosting',
      serviceName,
      buildId: BuildId
    })
    status = version.Status
    console.log('构建状态：', status)
  }

  if (status === 'SUCCESS') {
    const info = await app.cloudAppService.describeAppInfo({
      deployType: 'static-hosting',
      serviceName
    })
    console.log('部署成功！访问地址：', info.Domain)
  } else {
    console.error('部署失败')
  }
}

deployApp()

应用部署

createApp​

1. 接口描述​

2. 输入参数​

IStaticConfig​

IStaticCmd​

3. 返回结果​

describeAppList​

1. 接口描述​

2. 输入参数​

3. 返回结果​

CloudAppServiceItem​

describeAppInfo​

1. 接口描述​

2. 输入参数​

3. 返回结果​

deleteApp​

1. 接口描述​

2. 输入参数​

3. 返回结果​

describeAppVersion​

1. 接口描述​

2. 输入参数​

3. 返回结果​

describeAppVersionList​

1. 接口描述​

2. 输入参数​

3. 返回结果​

deleteAppVersion​

1. 接口描述​

2. 输入参数​

代码上传​

uploadCode​

1. 接口描述​

2. 输入参数​

3. 返回结果​

完整使用示例​

createApp

1. 接口描述

2. 输入参数

IStaticConfig

IStaticCmd

3. 返回结果

describeAppList

1. 接口描述

2. 输入参数

3. 返回结果

CloudAppServiceItem

describeAppInfo

1. 接口描述

2. 输入参数

3. 返回结果

deleteApp

1. 接口描述

2. 输入参数

3. 返回结果

describeAppVersion

1. 接口描述

2. 输入参数

3. 返回结果

describeAppVersionList

1. 接口描述

2. 输入参数

3. 返回结果

deleteAppVersion

1. 接口描述

2. 输入参数

代码上传

uploadCode

1. 接口描述

2. 输入参数

3. 返回结果

完整使用示例