配置文件

cloudbaserc.json 是云开发项目的核心配置文件，用于统一管理 CLI 和 VS Code 插件的部署配置。通过配置文件，您可以简化命令行操作，实现多环境部署和动态配置管理。

配置文件主要用于以下场景：

云函数部署：定义函数名称、运行时、超时时间、环境变量等配置
多环境管理：通过环境变量和动态变量支持开发、测试、生产等不同环境
跨工具共享：在 CLI 和 VS Code 插件间共享统一配置，避免重复设置

如需生成或初始化配置文件，请参考初始化配置；如需在本地与云端之间同步配置，请参考拉取配置与推送配置。

配置文件查找

CLI 在项目目录下按以下顺序查找，使用第一个命中的文件：

cloudbaserc
cloudbaserc.json
cloudbaserc.yaml
cloudbaserc.yml
cloudbaserc.js
cloudbase.config.js

package.json 中的对象型 cloudbase 字段同样受支持，且优先于上述文件。

项目目录由 --cwd / --workdir 指定，默认当前目录，见全局选项。指定 --cwd 时只在该目录查找，不向上级目录回溯；未找到即视为无配置。

指定 --config-file 时以其为准，相对当前目录解析，跳过上述查找。

JSON Schema

配置文件支持 JSON Schema 验证，可在编辑器中获得代码补全和验证提示。

Schema 地址：https://static.cloudbase.net/cli/cloudbaserc.schema.json

VS Code 配置示例（在 .vscode/settings.json 中添加）：

{
  "json.schemas": [
    {
      "fileMatch": ["cloudbaserc.json"],
      "url": "https://static.cloudbase.net/cli/cloudbaserc.schema.json"
    }
  ]
}

配置字段

以下是 cloudbaserc.json 支持的顶层配置字段，点击字段名可快速跳转：

字段	类型	说明
`version`	`String`	配置文件版本号
`envId`	`String`	云开发环境 ID
`region`	`String`	环境所在地域
`functionRoot`	`String`	云函数代码存放目录
`functions`	`Array<CloudFunction>`	云函数配置项数组
`integrations`	`Array<Integration>`	集成配置项数组
`app`	`Object`	静态托管应用部署配置
`gateway`	`Object`	网关路由配置
`hosting`	`Array<Object>`	静态托管应用配置
`database`	`Object`	数据库迁移配置

version

属性	值
类型	`String`
默认值	无需填写（可省略）
说明	配置文件版本号。当前 schema 仅接受 `"2.1"`；CLI 生成配置时不再写入该字段，省略即为最新格式
示例	`"version": "2.1"`（可选）

envId

属性	值
类型	`String`
说明	云开发环境 ID，环境的唯一标识符
示例	`"envId": "dev-abc123"`

region

属性	值
类型	`String`
说明	环境所在地域。上海地域可以省略，其他地域（如新加坡）必须填写
示例	`"region": "ap-singapore"`

functionRoot

属性	值
类型	`String`
说明	云函数代码存放目录，相对项目目录的路径
示例	`"functionRoot": "./functions"` 或 `"functionRoot": "functions"`

functions

云函数配置项数组，每个元素是一个 CloudFunction 对象，描述一个云函数的部署配置（基础配置、代码配置、环境变量、触发器、镜像等）。完整字段列表见配置文件-云函数。

属性	值
类型	`Array<CloudFunction>`
说明	每个元素描述一个云函数的部署配置（`name`、`runtime`、`timeout`、`envVariables` 等）

常用字段速览

name（必填）：函数部署后的标识符（同一 envId 下唯一），需与 gateway.routes[].target 中的 function:<name> 对应
runtime：运行时环境，支持 Nodejs16.13 / Nodejs18.15 / Nodejs20.19 / Python3.10 / Golang1.21 / PHP8.2 / Java17 等
timeout：超时时间 1-900 秒，默认 5
handler：处理方法名，格式 文件名.函数名（如 index.main），默认 index.main
memorySize：内存大小（MB），64-3072，默认 256
envVariables：环境变量，键值对，支持 {{env.NAME}} 引用外部变量；密钥类推荐用 KMS/SCF 密钥管理，不要硬编码
functionRoot（顶层）：所有函数的根目录，未指定 dir 时函数部署路径为 functionRoot/name
完整 30+ 字段按基础配置 / 代码和依赖 / 高级配置 / 触发器 / VPC / WebSocket / 并发 / 镜像分组见配置文件-云函数

示例：

{
  "functions": [
    {
      "name": "app",
      "timeout": 10,
      "runtime": "Nodejs16.13",
      "envVariables": {
        "API_KEY": "{{env.API_KEY}}"
      }
    }
  ]
}

integrations

集成配置项数组，每个元素描述一个集成中心的配置（微信支付、公众号、AI 工具等）。集成中心把凭证、回调、验签等模板化逻辑沉淀在平台层，业务方只需用云函数 SDK / HTTP 调用即可。完整字段列表见配置文件-集成。

属性	值
类型	`Array<Integration>`
说明	每个元素描述一个集成的配置（`keyId`、`authTypeCode`、`envVariables` 等）

常用字段速览

keyId（必填）：集成实例唯一标识，用于匹配云端已有实例；同一 envId 下唯一
authTypeCode（必填）：集成类型代码，决定集成中心部署哪种云函数模板，可用 tcb integration types 查询
envVariables：凭证型环境变量，由集成中心托管（业务代码不要硬编码），支持 @ 文件引用语法
demoCodeFunctionName：要绑定的云函数名称
完整字段、authTypeCode 常用取值、凭证字段、@ 文件引用语法见配置文件-集成

app

静态托管应用部署配置，用于 tcb app deploy / tcb deploy 命令。配置后可免去每次手动指定框架、构建命令等参数，支持零配置自动检测。完整字段列表、优先级总则与 CLI 参数对照见应用部署。

属性	值
类型	`Object`
说明	静态托管应用部署配置，用于 `tcb app deploy` / `tcb deploy` 命令

常用字段速览

serviceName：静态托管应用服务名称，默认取 package.json 的 name 或目录名
root：应用根目录（相对项目目录），monorepo 场景指定子项目路径
framework：前端框架 react / vue / vite / next / nuxt / angular / static
buildCommand / outputDir：构建命令与产物目录，纯静态项目可跳过构建
deployPath：静态托管挂载路径。缺前导 / 会自动补全（web → /web）并提示；含空白或 shell 特殊字符、含 ../、以 - 开头则报 INVALID_PARAM
完整 9 个字段、优先级总则、CLI 参数对照见应用部署

gateway

网关路由配置，用于 tcb deploy 声明式部署网关，定义如何将 HTTP 请求按“域名 + 路径”转发到云函数、静态托管等上游服务。完整字段列表见配置文件-网关。

属性	值
类型	`Object`
说明	CloudBase 网关路由配置，用于 `tcb deploy` 声明式部署网关

常用字段速览

routes（必填）：网关路由列表，每项描述一条“域名 + 路径 → 上游”的转发规则
routes[].path（必填）：URL 路径，如 /api，不支持通配符 *
routes[].target（必填）：目标资源 function:<name>（云函数）或 hosting:<name>（静态托管）
routes[].domain：绑定的自定义域名，未绑定时 tcb deploy 自动绑定（幂等）
routes[].accessType：域名接入方式 DIRECT / CDN / CUSTOM / EO
完整 13 个 routes[] 字段及接入方式、协议、证书、限频等补充说明见配置文件-网关

hosting

静态托管应用配置（数组，多站点），用于 tcb deploy 声明式部署静态托管。构建与部署分离：先执行 tcb app build 本地构建产物，tcb deploy 仅上传产物（不自动执行本地构建）；纯静态（无 buildCommand）直接上传。完整字段列表见静态网站托管。

属性	值
类型	`Array<Object>`
说明	静态托管应用配置，用于 `tcb deploy` 声明式部署静态托管

常用字段速览

name（必填）：应用名称，同一配置文件内唯一，被 gateway.routes[].target: hosting:<name> 引用
root：应用根目录（相对项目目录），用于 monorepo
framework：前端框架 react / vue / vite / vite-react / vite-vue / next / nuxt / angular / static / custom
buildCommand / outputDir：构建命令与产物目录，纯静态项目直接上传 outputDir
deployPath：静态资源部署路径，应以 / 开头；缺前导 / 会自动补全（sub → /sub）并提示，含空白或 shell 特殊字符、含 ../、以 - 开头则报 INVALID_PARAM。多个 hosting 不可重复
完整 9 个字段、框架预设、与 app.envVariables 的关系见静态网站托管

database

数据库迁移配置，用于 tcb deploy 声明式执行 SQL 迁移。

属性	值
类型	`Object`
说明	数据库迁移配置，用于 `tcb deploy` 声明式执行 SQL 迁移

子字段：

字段	类型	必填	默认值	说明
`type`	String	是	—	数据库类型，目前仅支持 `postgresql`
`migrations`	String	否	`./cloudbase/migrations`	迁移文件目录（相对项目目录，仅支持相对路径）

{
  "database": {
    "type": "postgresql",
    "migrations": "./cloudbase/migrations"
  }
}

迁移文件使用 <14位时间戳>_<名称>.sql 命名，例如 20240101120000_init.sql。CLI 按文件名字典序升序执行，成功执行的文件记录在 __migrations 表中，不重复执行。

声明式迁移不支持自动回滚，需要手动编写反向 SQL。手工管理迁移记录见修复迁移记录。

完整配置示例

以下是一个包含常用配置的完整示例：

{
  "envId": "{{env.TCB_ENV_ID}}",
  "region": "ap-shanghai",
  "functionRoot": "./functions",
  "functions": [
    {
      "name": "api",
      "timeout": 10,
      "runtime": "Nodejs16.13",
      "memorySize": 256,
      "envVariables": {
        "DB_HOST": "{{env.DB_HOST}}",
        "API_KEY": "{{env.API_KEY}}"
      },
      "installDependency": true
    },
    {
      "name": "task",
      "timeout": 30,
      "runtime": "Nodejs16.13",
      "triggers": [
        {
          "name": "dailyTask",
          "type": "timer",
          "config": "0 0 2 * * * *"
        }
      ]
    }
  ],
  "integrations": [
    {
      "keyId": "myPayment",
      "authTypeCode": "weixinpaydc",
      "envVariables": {
        "MCH_ID": "1234567890",
        "API_KEY": "your-api-key"
      }
    }
  ],
  "hosting": [
    {
      "name": "web",
      "root": "./web",
      "framework": "vite",
      "outputDir": "dist",
      "buildCommand": "npm run build",
      "installCommand": "npm install",
      "deployPath": "/",
      "envVariables": {
        "VITE_APP_ID": "your-app-id"
      },
      "ignore": ["node_modules", ".git"]
    }
  ],
  "gateway": {
    "routes": [
      {
        "path": "/api",
        "target": "function:api"
      },
      {
        "path": "/",
        "target": "hosting:web"
      }
    ]
  },
  "database": {
    "type": "postgresql",
    "migrations": "./cloudbase/migrations"
  }
}

动态变量

配置文件支持动态变量特性：使用 {{}} 语法从环境变量或其他数据源动态获取配置值。该能力不依赖 version 字段（"2.0" 已不被当前 schema 接受，写入会导致校验失败）。

💡 注意: 动态变量仅在 JSON 格式的配置文件中可用

基本示例：

{
  "envId": "{{env.ENV_ID}}",
  "functionRoot": "./functions",
  "functions": [
    {
      "name": "{{env.FUNCTION_NAME}}",
      "timeout": 5
    }
  ]
}

数据源

CloudBase 提供了多个命名空间用于访问不同的数据源。通过 命名空间.变量名 的格式引用变量，例如 {{tcb.envId}}。

支持的数据源：

命名空间	变量名	说明	示例
`tcb`	`envId`	配置文件或命令行参数指定的环境 ID	`{{tcb.envId}}`
`util`	`uid`	24 位随机字符串，可用于生成唯一标识	`{{util.uid}}`
`env`	`*`	从 `.env` 文件加载的所有环境变量	`{{env.API_KEY}}`

环境变量

CloudBase 对环境变量提供了增强支持，帮助您在不同开发阶段（开发、测试、生产）使用不同的配置。通过 .env 文件管理环境变量，支持按运行模式自动加载对应配置。

文件加载规则

CloudBase 支持以下 .env 文件类型：

.env                # 所有环境共享的基础配置
.env.local          # 本地私密配置（建议加入 .gitignore）
.env.[mode]         # 特定模式的配置（如 .env.production、.env.development）

加载顺序：

默认加载：.env 和 .env.local 始终被加载
模式加载：使用 --mode <mode> 参数时，额外加载 .env.[mode] 文件
覆盖规则：.env.[mode] > .env.local > .env（后加载的文件会覆盖同名变量）

示例：

# 部署时指定测试模式
tcb framework deploy --mode test

执行上述命令时，会按顺序加载 .env、.env.local、.env.test 三个文件，并合并环境变量。

最佳实践

将 API 密钥、数据库密码等私密信息存放在 .env.local 文件中，并将其添加到 .gitignore，避免敏感信息泄露。

使用示例

.env.local 文件：

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=s1mpl3

cloudbaserc.json 配置：

{
  "envId": "xxx",
  "functionRoot": "./functions",
  "functions": [
    {
      "name": "database",
      "envVariables": {
        "DB_HOST": "{{env.DB_HOST}}",
        "DB_USER": "{{env.DB_USER}}",
        "DB_PASSWORD": "{{env.DB_PASSWORD}}"
      }
    }
  ]
}

扩展语法

除了基本的键值对，CloudBase 支持在 .env 文件中使用复合键值对语法，通过 . 符号构建嵌套对象和数组结构。

基础键值对

FOO=bar
VUE_APP_SECRET=secret

复合键值对

使用 . 符号为同一键添加属性，支持对象和数组嵌套：

Book.Name=Test
Book.Publish=2020
Book.Authors.0=Jack
Book.Authors.1=Mike

编译结果：

上述配置会被解析为以下 JSON 对象：

{
  "Name": "Test",
  "Publish": "2020",
  "Authors": ["Jack", "Mike"]
}

在配置文件中引用

您可以在 cloudbaserc.json 中直接引用对象属性：

{
  "envId": "xxx",
  "functionRoot": "./functions",
  "functions": [
    {
      "name": "app",
      "envVariables": {
        "BOOK_NAME": "{{env.Book.Name}}",
        "FIRST_AUTHOR": "{{env.Book.Authors.0}}"
      }
    }
  ]
}

对象引用规则

当引用整个对象时（如 {{env.Book}}），编译时会自动转换为 JSON 字符串：

{{env.Book}} → {"Name":"Test","Publish":"2020","Authors":["Jack","Mike"]}

更多云函数配置项的详细说明，请参考配置文件-云函数。

更多集成配置的详细说明，请参考配置文件-集成。

注意事项

tcb app deploy 与 tcb deploy 读同一份 app 配置，自 v3.9.0 起构建行为不同：

	`tcb app deploy`	`tcb deploy`（声明式）
构建	云端构建（安装依赖 + 执行 `buildCommand`）	不构建，直传 `outputDir` 产物
`outputDir`	可省略（交互询问 / 默认 `dist`）	未配置时按 `buildCommand` / `framework` / `package.json` 推断，纯静态回退项目根
`installCommand` / `buildCommand`	生效	被忽略，改用 `tcb app build` 本地构建

需要云端构建用 tcb app deploy，只部署已就绪产物用 tcb deploy，详见声明式部署 · 注意事项。

配置文件查找​

JSON Schema​

配置字段​

version​

envId​

region​

functionRoot​

functions​

integrations​

app​

gateway​

hosting​

database​

完整配置示例​

动态变量​

数据源​

环境变量​

文件加载规则​

使用示例​

扩展语法​

基础键值对​

复合键值对​

在配置文件中引用​

注意事项​

配置文件查找

JSON Schema

配置字段

version

envId

region

functionRoot

functions

integrations

app

gateway

hosting

database

完整配置示例

动态变量

数据源

环境变量

文件加载规则

使用示例

扩展语法

基础键值对

复合键值对

在配置文件中引用

注意事项