支持地域：上海

使用 CloudBase CLI 部署静态应用到私有化环境

本文档将指导您使用 CloudBase CLI，将前端静态应用（React / Vue / Vite 等）部署到微搭私有部署环境。

前提条件

环境要求

微搭环境：已完成私有部署，并已知环境 ID 与平台地址
账号凭证：私有化环境的控制台账号与密码
CLI：@cloudbase/cli 3.8.7 及以上（本能力自 3.8.7 起提供，可用 tcb -v 确认版本）
本地环境：已安装 Node.js，且项目可在本地正常构建

步骤 1：配置 cloudbaserc.json

在项目根目录的 cloudbaserc.json 中增加私有化配置：

{
  "envId": "software-xxxxxxxxxxxx",
  "privateSettings": {
    "credential": {
      "weda": {
        "username": "admin",
        "password": "******"
      }
    },
    "endpoints": {
      "cliApi": "http://your-private-domain.com"
    }
  },
  "app": {
    "serviceName": "my-app",
    "framework": "vite",
    "outputDir": "dist"
  }
}

字段说明：

字段	必填	说明
`envId`	是	私有化环境 ID
`privateSettings.credential.weda.username` / `password`	是	私有化环境控制台账号，是该形态下唯一可用的登录凭证
`privateSettings.endpoints.cliApi`	是	私有化平台地址，需带协议（如 `http://1.2.3.4`）
`privateSettings.privateUin`	否	私有化环境的用户 uin
`app.serviceName`	否	应用名称，决定访问地址的子路径与版本名前缀（如 `my-app-003`）；缺省时按位置参数 → 交互选择 → 项目目录名取值
`app.outputDir`	是	构建产物目录，私有化部署下的关键配置，见步骤 2
`app.deployPath`	否	访问子路径，默认 `/<app.serviceName>`，改动后访问地址随之变化
`app.ignore`	否	追加的忽略规则，私有化下需显式配置，见「注意事项」
`app.envVariables`	否	在私有化下不生效：不会注入到本地构建，请在本地构建时自行设置（如 `.env`）

无需登录

配置存在 privateSettings 时，CLI 会自动识别私有化环境并完成鉴权，无需执行 tcb login，也不需要配置对象存储密钥。

步骤 2：本地构建产物

重要：私有化环境不支持云端构建

公有云部署由服务端执行「安装依赖 → 构建」，而私有化环境不提供云端构建能力，必须先在本地构建出产物目录。

若产物目录不存在，执行部署会直接报错并提示先本地构建。

npm install
npm run build

构建完成后，请确认 app.outputDir（默认 dist）目录已生成。

步骤 3：执行部署

tcb app deploy

常用参数（完整清单见 tcb app deploy -h）：

参数	说明	私有化下是否生效
`[serviceName]`	位置参数，应用名称；缺省时按 `app.serviceName` → 交互选择 → 项目目录名取值	是
`-e, --env-id <envId>`	覆盖环境 ID（`--envId` 为废弃别名）	是
`--output-dir <dir>`	覆盖 `app.outputDir`，决定上传哪个目录	是
`--deploy-path <path>`	覆盖 `app.deployPath`	是
`--cwd <path>`	项目目录，相对路径（默认当前目录）	是
`--ignore <patterns>`	忽略规则，逗号分隔，追加在 `app.ignore` 之后	是
`--enable-git-ignore`	合并项目 `.gitignore` 规则（默认不合并）	是
`-f, --force`	应用名已存在时跳过确认，直接覆盖更新（CI 场景建议加上）	是
`--framework <fw>`	框架类型，随版本记录展示（`static` 按 `other` 处理）	仅记录
`--install-command` / `--build-command`	安装 / 构建命令	否，见步骤 2

执行过程中 CLI 会依次完成：打包产物目录 → 上传 → 创建云应用 → 轮询构建状态。

步骤 4：访问应用

部署成功后，终端会输出访问地址与版本号：

部署成功！
  访问地址: http://your-private-domain.com/my-app/
  版本号: my-app-003
  耗时: 32s

提示

应用访问地址形如 http://<域名>/<服务名>，末尾是否带斜杠取决于平台返回的域名，以终端实际输出为准。若输出的是兜底地址，请以平台控制台中显示的应用域名为准。

应用查询与删除

私有化环境同样支持应用管理类命令：

命令	说明
`tcb app list`	查看环境下的应用列表
`tcb app info <serviceName>`	查看指定应用的详情
`tcb app versions list <serviceName>`	查看应用版本历史
`tcb app versions detail <serviceName>`	查看指定版本详情（默认最新版本）
`tcb app delete <serviceName>`	删除应用及其所有版本（支持 `--dry-run` 预览）

tcb app list
tcb app info my-app
tcb app versions list my-app
tcb app versions detail my-app

# 删除前建议先预览
tcb app delete my-app --dry-run

提示

输出的访问地址按平台协议展示（http://<域名>/<服务名>）
app versions detail 未指定 --version-name 时会自动取最新版本
app delete 会同时删除该应用的所有版本且不可恢复，建议先加 --dry-run 确认目标

关于 tcb app build

私有化环境下不提供 tcb app build。

该命令用于构建声明式配置（cloudbaserc.json 的 hosting[]）中的静态托管项目，产物由 tcb deploy / tcb hosting deploy 消费 —— 而私有化环境没有静态托管服务，这两条链路均不可用，产物无处落地；且它只处理 hosting[]，不处理本节使用的 app 字段。

请直接使用项目自身的构建命令（如 npm run build）产出 app.outputDir 即可。

与公有云部署的差异

维度	公有云	私有化（软件化）
构建位置	云端（服务端执行）	本地，需先构建产物
上传内容	项目源码	`app.outputDir` 产物目录的内容
`app.installCommand` / `app.buildCommand`	下发到服务端执行	被忽略，并打印提示
`app.framework: "static"`	走静态托管直传链路	按 `other` 处理
访问地址格式	`https://{envId}-{appId}.tcloudbaseapp.com`	`http://<域名>/<服务名>`（以终端实际输出为准）
登录方式	`tcb login`	配置文件中的账号密码

上传的是产物而非源码

私有化环境会把上传包的根目录直接作为站点内容发布。CLI 已按 app.outputDir 自动定位上传目录，因此请务必先完成本地构建，并确保 outputDir 配置正确。

注意事项

命令范围：私有化环境下 CLI 只注册受支持的命令，可执行 tcb -h 查看当前可用清单
不支持 SPA 路由回退：访问无扩展名的路径会返回 NoSuchKey，不会回退 index.html，使用 React Router 等时建议改用 hash 模式
仅支持静态托管类型：私有化环境仅支持 static-hosting 部署类型，CLI 已固定使用
不输出云端构建日志链接：私有化环境无对应的控制台页面，故不输出该链接
app.ignore 需显式配置：app deploy 链路不会默认排除 node_modules；当 outputDir 指向项目根（.）时必须自行配置，否则依赖目录会被一起打进部署包（裸目录名会自动补 /**，写 node_modules 即可）。.git、.DS_Store 由 CLI 强制排除，无需重复配置

常见问题

现象	原因与解决
提示「不是有效的命令」	该命令在私有化环境未支持，可执行 `tcb -h` 查看可用命令
提示缺少私有化凭证	`privateSettings.credential.weda` 未配置；仅配置 `secretId` / `secretKey` 不适用于该形态
提示缺少平台地址	`privateSettings.endpoints.cliApi` 未配置
提示「请先在本地构建并产出 dist」	产物目录不存在，先执行 `npm run build`
站点能打开但静态资源 404	上传了源码目录而非产物目录，请检查 `app.outputDir` 配置
报错「`app.outputDir` 解析后超出项目目录」	`outputDir` 写成了 `../` 或绝对路径；上传目录必须落在项目内，请改为项目内相对路径（如 `dist`）
报错「`app.outputDir` 经由符号链接逃逸出项目目录」	`outputDir` 指向的目录是软链、且真实路径在项目外；请移除该软链，或在构建阶段把外部内容复制进项目内
部署失败	错误信息中会携带请求 ID，可提供给平台侧排查

前提条件​

步骤 1：配置 cloudbaserc.json​

步骤 2：本地构建产物​

步骤 3：执行部署​

步骤 4：访问应用​

应用查询与删除​

与公有云部署的差异​

注意事项​

常见问题​