配置文件

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

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

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

快速开始

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

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

# 使用自定义配置文件
tcb deploy --config-file custom-config.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）

加载顺序：

1. 默认加载：.env 和 .env.local 始终被加载
2. 模式加载：使用 --mode <mode> 参数时，额外加载 .env.[mode] 文件
3. 覆盖规则：.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}}"
      }
    }
  ]
}

完整配置示例

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

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