配置文件

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

integrations

类型：Array<Integration>
说明：集成配置项数组，每个元素描述一个集成的配置
详细说明：查看集成中心概述

示例：

{
  "integrations": [
    {
      "name": "myPayment",
      "authTypeCode": "weixinpaydc",
      "envVariables": {
        "MCH_ID": "1234567890",
        "API_KEY": "your-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 * * * *"
        }
      ]
    }
  ],
  "integrations": [
    {
      "name": "myPayment",
      "authTypeCode": "weixinpaydc",
      "envVariables": {
        "MCH_ID": "1234567890",
        "API_KEY": "your-api-key"
      }
    }
  ]
}

配置文件操作

初始化配置

tcb config init 命令用于从模板创建配置文件，帮助您快速初始化云函数或集成的配置模板。

命令格式

tcb config init <module> [options]

其中 <module> 表示要初始化的模块，目前支持：

模块	说明
`fn`	初始化云函数配置模板
`integration`	初始化集成配置模板

命令参数

参数	说明	必填
`--name <name>`	配置项名称（云函数名或集成名）	否（交互式输入）
`--type <type>`	集成类型（仅 integration 模块），如 `weixinpaydc`	否（交互式选择）
`-o, --output <output>`	输出文件路径，默认为当前目录下的 cloudbaserc.json	否

使用示例

初始化云函数配置：

# 交互式创建云函数配置
tcb config init fn

# 指定函数名创建配置
tcb config init fn --name myFunction

# 指定输出文件
tcb config init fn --name myFunction -o ./config/cloudbaserc.json

初始化集成配置：

# 交互式选择集成类型并创建配置
tcb config init integration

# 指定集成类型和名称
tcb config init integration --type weixinpaydc --name myPayment

# 指定输出文件
tcb config init integration --type weixinpaydc --name myPayment -o ./config/cloudbaserc.json

初始化行为

云函数配置：

生成包含基本字段的函数配置模板（name、timeout、runtime、envVariables 等）
envVariables 字段会根据集成类型自动填充占位符，提示必填/可选项

集成配置：

从云端拉取集成类型的模板字段定义
自动识别必填字段和可选字段
对敏感字段（如密钥、证书）使用占位符 ******，提示用户填写真实值
生成包含 authTypeCode、name、envVariables 的完整配置

使用场景

快速开始：通过模板快速创建符合规范的配置文件
配置学习：了解云函数或集成需要配置哪些字段
团队协作：生成标准化的配置模板，团队成员只需填写具体值

拉取配置

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

命令格式

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

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

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

命令行为

拉取云函数配置（tcb config pull fn）：

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

拉取集成配置（tcb config pull integration）：

查询云端配置：根据指定的集成名称，从云端获取已创建集成的完整配置（authTypeCode、envVariables 等）。
敏感字段脱敏：对密码类型的字段（如 API 密钥、证书等），云端返回的值为 ****** 占位符，需要用户手动填写真实值。
合并写入本地：
- 若本地 cloudbaserc.json 不存在，则自动创建并写入拉取的配置。
- 若文件已存在，对同名集成配置，CLI 会询问是否覆盖；对不同名集成，则追加到 integrations 数组。
集成不存在时：返回错误提示，建议用户使用 tcb config init integration 创建配置模板。

命令参数

参数	说明	必填
`[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

拉取集成配置：

# 拉取单个集成的配置
tcb config pull integration myPayment

# 拉取多个集成的配置
tcb config pull integration payment1 payment2

# 拉取配置文件中所有集成的配置
tcb config pull integration --all

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

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

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

使用场景

云函数配置：

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

集成配置：

快速同步：从云端拉取已创建的集成配置，避免手动填写 authTypeCode 等复杂字段。
配置备份：将云端集成配置导出到本地，便于版本管理和备份。
团队协作：团队成员可以快速同步集成配置，只需填写敏感字段的真实值。

推送配置

tcb config update 命令用于将 cloudbaserc.json 中的配置推送到云端，实现本地配置与云端资源的同步。

命令格式

tcb config update <module> [name] [options]

其中 <module> 表示要推送的模块，目前支持：

模块	说明
`fn`	推送云函数配置
`integration`	推送集成配置

命令参数

参数	说明	必填
`[name]`	资源名称（云函数名或集成名）	否（与 `--all` 二选一）
`--all`	推送配置文件中所有资源的配置	否
`-e, --env-id <envId>`	环境 ID	否
`--timeout <timeout>`	[fn] 超时时间（秒）	否
`--memory <memory>`	[fn] 内存大小（MB）	否
`--runtime <runtime>`	[fn] 运行时	否
`--handler <handler>`	[fn] 入口函数	否
`--vpc <vpcId/subnetId>`	[fn] VPC 配置（格式: vpcId/subnetId）	否
`--yes`	跳过交互确认	否

使用示例

推送云函数配置：

# 推送单个函数的配置
tcb config update fn hello

# 推送单个函数配置，并覆盖 timeout 参数
tcb config update fn hello --timeout 30

# 批量推送配置文件中所有函数的配置
tcb config update fn --all

# 推送函数配置并指定 VPC
tcb config update fn myFunc --vpc vpc-xxx/subnet-xxx

推送集成配置：

# 推送单个集成的配置
tcb config update integration myPayment

# 批量推送配置文件中所有集成的配置
tcb config update integration --all

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

推送行为

推送云函数配置（tcb config update fn）：

读取本地配置：从 cloudbaserc.json 的 functions 字段读取函数配置。
参数优先级：CLI 参数（如 --timeout）> 配置文件中的值。
环境变量处理：
- 若配置中包含环境变量，CLI 会询问更新方式：
  - 覆盖更新：用本地环境变量完全替换云端环境变量
  - 合并更新：本地与云端环境变量合并，本地覆盖同名变量
批量推送：使用 --all 参数时，会推送配置文件中所有函数的配置。

推送集成配置（tcb config update integration）：

读取本地配置：从 cloudbaserc.json 的 integrations 字段读取集成配置。
匹配云端实例：根据配置中的 name 字段匹配云端已有的集成实例。
智能合并：
- 对于可选字段（如 demoCodeFunctionName），若本地配置显式设置为空字符串 ''，则会清除云端对应字段
- 对于必填字段（如 authTypeCode），若本地未指定，则保留云端原值
批量推送：使用 --all 参数时，会推送配置文件中所有集成的配置。

使用场景

云函数配置：

配置同步：将本地修改的函数配置推送到云端，保持一致。
批量更新：通过 --all 参数一次性更新多个函数的配置。
参数覆盖：临时修改某个参数（如 --timeout）而不修改配置文件。

集成配置：

凭证轮换：更新集成的凭证信息（如 API 密钥、证书等）。
配置管理：通过配置文件统一管理多个集成的配置。
团队协作：团队成员通过配置文件同步集成配置，只需填写敏感字段。

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

更多集成配置的详细说明，请参考集成中心概述。

快速开始​

JSON Schema​

动态变量​

数据源​

环境变量​

文件加载规则​

使用示例​

扩展语法​

基础键值对​

复合键值对​

在配置文件中引用​

配置字段​

version​

envId​

region​

functionRoot​

functions​

integrations​

app​

完整配置示例​

配置文件操作​

初始化配置​

命令格式​

命令参数​

使用示例​

初始化行为​

拉取配置​

命令格式​

命令行为​

命令参数​

使用示例​

推送配置​

命令格式​

命令参数​

使用示例​

推送行为​

快速开始

JSON Schema

动态变量

数据源

环境变量

文件加载规则

使用示例

扩展语法

基础键值对

复合键值对

在配置文件中引用

配置字段

version

envId

region

functionRoot

functions

integrations

app

完整配置示例

配置文件操作

初始化配置

命令格式

命令参数

使用示例

初始化行为

拉取配置

命令格式

命令行为

命令参数

使用示例

推送配置

命令格式

命令参数

使用示例

推送行为