配置文件

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

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

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

快速开始

使用 tcb init 初始化项目时，会自动生成 cloudbaserc.json 配置文件。您也可以通过 --config-file 参数指定自定义配置文件路径。

# 初始化项目，自动生成 cloudbaserc.json
tcb init

# 使用自定义配置文件
tcb deploy --config-file custom-config.json

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"
    }
  ]
}

动态变量

从 CLI 0.9.1 版本开始，配置文件支持 2.0 版本格式，引入了动态变量特性。通过在 cloudbaserc.json 中声明 "version": "2.0"，您可以使用 {{}} 语法从环境变量或其他数据源动态获取配置值。

💡 注意: 2.0 版本配置文件仅支持 JSON 格式

基本示例：

{
  "version": "2.0",
  "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 配置：

{
  "version": "2.0",
  "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 中直接引用对象属性：

{
  "version": "2.0",
  "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"]}

配置字段

以下是 cloudbaserc.json 支持的主要配置字段及其说明。

version

类型：String
说明：配置文件版本号，当前支持 "2.0"。未指定时默认为 "1.0" 版本
示例："version": "2.0"

envId

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

region

类型：String
说明：环境所在地域。上海地域可以省略，其他地域（如广州、北京）必须填写
示例："region": "ap-guangzhou"

functionRoot

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

functions

类型：Array<CloudFunction>
说明：函数配置项数组，每个元素描述一个云函数的部署配置
详细说明：查看函数配置项文档

示例：

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

app

类型：Object
说明：云应用部署配置，用于 tcb app deploy / tcb deploy 命令。配置后可免去每次手动指定框架、构建命令等参数，支持零配置自动检测。
详细说明：查看应用部署文档

字段	类型	必填	默认值	说明
`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 模式，默认已排除 `node_modules` 和 `.git`

优先级总则：CLI 参数 > cloudbaserc.json 配置 > 自动检测 > 交互式输入

⚠️ 注意：部分参数有特殊规则（如 envVariables 无 CLI 参数，buildCommand 有框架默认值等），详细优先级请参考应用部署文档。

示例：

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

完整配置示例

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

{
  "version": "2.0",
  "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 * * * *"
        }
      ]
    }
  ]
}

配置文件操作

拉取配置

tcb config pull 命令用于从云端拉取已部署资源的配置，并写入本地 cloudbaserc.json，帮助您快速同步云端状态或初始化本地配置文件。

命令格式

tcb config pull <module> [name...] [options]

其中 <module> 表示要拉取的资源模块，目前支持：

模块	说明
`fn`	拉取云函数配置

命令行为

执行 tcb config pull fn 时，CLI 将执行以下操作：

查询云端配置：根据指定的函数名称，从云端获取已部署云函数的完整配置（超时时间、内存、运行时、环境变量、触发器等）。
合并写入本地：
- 若本地 cloudbaserc.json 不存在，则自动创建并写入拉取的配置。
- 若文件已存在，对同名函数配置，CLI 会询问是否覆盖；对不同名函数，则追加到 functions 数组。
云函数不存在时：CLI 会询问是否根据本地项目目录推测配置并写入。

命令参数

参数	说明	必填
`[name...]`	云函数名称，支持指定一个或多个	否
`--all`	拉取配置文件中所有函数的配置	否
`-e, --env-id <envId>`	环境 ID	否
`-o, --output <output>`	输出文件路径，默认为当前目录下的 cloudbaserc.json	否
`--stdout`	将结果输出到控制台而非写入文件	否
`--code-secret <codeSecret>`	代码加密函数的 CodeSecret	否
`--dir <dir>`	指定目录用于推测配置（当云函数不存在时）	否
`--yes`	跳过交互确认，自动覆盖已存在的配置	否

使用示例

# 拉取单个函数的配置
tcb config pull fn myFunc

# 拉取多个函数的配置
tcb config pull fn func1 func2 func3

# 拉取配置文件中所有函数的配置
tcb config pull fn --all

# 将结果输出到控制台（不写文件）
tcb config pull fn func1 --stdout

# 指定输出文件路径
tcb config pull fn myFunc -o ./config/cloudbaserc.json

# 自动确认，跳过交互提示
tcb config pull fn --all --yes

使用场景

初始化本地配置：在新环境或新机器上，通过 pull 快速从云端同步配置，无需手动填写。
配置审查：拉取后结合 tcb config diff fn 命令，对比本地与云端配置差异。
团队协作：将拉取结果提交到版本库，确保团队成员使用一致的函数配置。 :::

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

配置文件

快速开始​

JSON Schema​

动态变量​

数据源​

环境变量​

文件加载规则​

使用示例​

扩展语法​

基础键值对​

复合键值对​

在配置文件中引用​

配置字段​

version​

envId​

region​

functionRoot​

functions​

app​

完整配置示例​

配置文件操作​

拉取配置​

命令格式​

命令行为​

命令参数​

使用示例​

快速开始

JSON Schema

动态变量

数据源

环境变量

文件加载规则

使用示例

扩展语法

基础键值对

复合键值对

在配置文件中引用

配置字段

version

envId

region

functionRoot

functions

app

完整配置示例

配置文件操作

拉取配置

命令格式

命令行为

命令参数

使用示例