配置文件-云函数

在 CloudBase CLI 配置文件 cloudbaserc.json 中,通过 functions 数组可以定义多个云函数的配置项,这些配置项控制着函数的部署行为和运行时特性。

配置扁平化

从 CLI 0.6.0 版本起,functions 选项中的 config 选项已扁平化处理,原有嵌套在 config 中的所有配置项现在可以直接写在 functions 数组项中,使用更加简便。

快速示例

一个典型的云函数配置示例:

{
  "envId": "dev-xxxx",
  "functionRoot": "./functions",
  "functions": [
    {
      "name": "app",
      "timeout": 5,
      "runtime": "Nodejs18.15",
      "installDependency": true,
      "handler": "index.main"
    }
  ]
}

配置项详解

基础配置项

配置项	必填	类型	默认值	描述
`functionRoot`	否	String	-	所有云函数的根目录,若未指定 `dir`,则函数部署路径为 `functionRoot/name`
`name`	是	String	-	云函数名称,即函数部署后的标识符
`type`	否	String	`Event`	函数类型,可选值: `Event`(事件触发函数)、`HTTP`(HTTP 云函数)
`dir`	否	String	-	云函数代码所在的文件夹路径,指定后将作为函数部署路径
`handler`	否	String	`index.main`	函数处理方法名称,格式为 `文件名.函数名` Java 运行时必须指定完整路径,如 `package.Class::mainHandler`
`runtime`	否	String	`Nodejs18.15`	运行时环境,详见运行时环境
`timeout`	否	Number	5	函数超时时间,取值范围 1-900 秒
`memorySize`	否	Number	256	函数内存大小(MB),取值范围 64-3072
`protocolType`	否	String	-	HTTP 函数支持的访问协议,当前支持 WebSocket 协议,值为 `WS`
`protocolParams`	否	Object	-	协议参数配置,详见 WebSocket 配置
`instanceConcurrencyConfig`	否	Object	-	实例并发配置,详见并发配置
`imageConfig`	否	Object	-	镜像部署配置,详见镜像配置

代码和依赖配置

配置项	必填	类型	默认值	描述
`ignore`	否	String/Array	-	部署时忽略的文件或目录,支持 glob 匹配规则建议忽略 `node_modules`、`.git` 等
`installDependency`	否	Boolean	`false`	是否在云端自动安装依赖包(仅支持 Node.js 运行时)
`codeSecret`	否	String	-	代码加密密钥,由 36 位大小写字母和数字组成

高级配置

配置项	必填	类型	默认值	描述
`envVariables`	否	Object	-	环境变量键值对,部署时会完全覆盖线上配置
`vpc`	否	Object	-	私有网络配置,详见VPC 配置
`triggers`	否	Array	-	触发器配置,详见触发器配置
`params`	否	Object	-	CLI 调用云函数时的默认入参
`role`	否	String	-	函数绑定的角色名称，用于日志投递等场景
`clsLogsetId`	否	String	-	CLS 日志集 ID，镜像部署时需要手动配置
`clsTopicId`	否	String	-	CLS 日志主题 ID，镜像部署时需要手动配置

运行时环境

CloudBase 云函数支持以下运行时环境:

Node.js 运行时

Nodejs20.19 (公测中)
Nodejs18.15 (推荐)
Nodejs16.13
Nodejs14.18
Nodejs12.16
Nodejs10.15

其他语言运行时

Php8.0
Php7.4
Php7.2
Python3.10
Python3.9
Python3.7
Python3.6
Golang1
Java11
Java8

运行时说明

Node.js 项目默认使用 Nodejs18.15 运行时,可以省略 runtime 配置
PHP、Java 等非 Node.js 运行时必须显式指定 runtime 值
启用 codeSecret 代码加密后,将无法在小程序 IDE 和腾讯云控制台中查看云函数源代码

触发器配置

触发器配置项用于定义云函数的自动触发规则:

配置项	必填	类型	描述
`name`	是	String	触发器名称,最大支持 60 个字符支持字符: `a-z`、`A-Z`、`0-9`、`-` 和 `_`,必须以字母开头
`type`	是	String	触发器类型,目前仅支持 `timer` (定时触发器)
`config`	是	String	触发器配置,定时触发器使用标准 Cron 表达式

配置示例:

{
  "triggers": [
    {
      "name": "myTrigger",
      "type": "timer",
      "config": "0 0 2 1 * * *"
    }
  ]
}

触发器限制

目前每个云函数仅支持配置一个触发器。详细的触发器管理请参考触发器文档。

VPC 配置

私有网络配置项用于将云函数部署到指定的 VPC 网络中:

配置项	必填	类型	描述
`vpcId`	是	String	VPC 网络 ID
`subnetId`	是	String	VPC 子网 ID

配置示例:

{
  "vpc": {
    "vpcId": "vpc-xxx",
    "subnetId": "subnet-xxx"
  }
}

WebSocket 配置

WebSocket 协议参数配置,需配合 protocolType: "WS" 使用:

配置项	必填	类型	描述
`wsParams.idleTimeOut`	否	Number	WebSocket 空闲超时时间(秒),取值范围 10~7200

配置示例:

{
  "protocolType": "WS",
  "protocolParams": {
    "wsParams": {
      "idleTimeOut": 110
    }
  }
}

并发配置

单实例多并发配置,仅支持 HTTP 云函数:

配置项	必填	类型	描述
`maxConcurrency`	否	Number	单实例最大并发数,取值范围 2~100
`dynamicEnabled`	否	String	是否开启智能动态并发。`FALSE` 为静态并发,空字符串 `''` 取消多并发配置

配置示例:

{
  "instanceConcurrencyConfig": {
    "maxConcurrency": 40,
    "dynamicEnabled": "FALSE"
  }
}

镜像配置

云函数支持通过容器镜像部署,适用于需要自定义运行环境、使用非标准语言或依赖复杂系统库的场景。

配置项	必填	类型	描述
`imageType`	是	String	镜像类型：`enterprise`（企业版）或 `personal`（个人版）
`imageUri`	是	String	镜像地址,格式：`registry/namespace/image:tag`
`registryId`	否	String	企业版镜像仓库 ID,企业版必填
`imagePort`	否	Number	容器监听端口,默认 9000
`entryPoint`	否	String	容器启动命令
`commandList`	否	String[]	启动命令列表
`argsList`	否	String[]	启动参数列表
`containerImageAccelerate`	否	Boolean	是否开启镜像加速

镜像类型说明:

类型	说明	registryId
`personal`	个人版镜像仓库	不需要
`enterprise`	企业版镜像仓库（TCR）	必填

配置示例（个人版）:

{
  "functions": [
    {
      "name": "image-function",
      "timeout": 30,
      "memorySize": 512,
      "imageConfig": {
        "imageType": "personal",
        "imageUri": "<访问域名>/your-namespace/your-image:tag",
        "imagePort": 9000
      }
    }
  ]
}

配置示例（企业版）:

{
  "functions": [
    {
      "name": "enterprise-func",
      "timeout": 60,
      "memorySize": 1024,
      "imageConfig": {
        "imageType": "enterprise",
        "imageUri": "<访问域名>/namespace/app:v1.0.0",
        "registryId": "tcr-xxxxxxxx",
        "imagePort": 8080,
        "containerImageAccelerate": true,
        "commandList": ["/app/start.sh"],
        "argsList": ["--config", "/app/config.json"]
      }
    }
  ]
}

镜像部署注意事项

镜像地址格式：必须包含标签（tag），如 :latest 或 :v1.0.0
端口配置：默认监听 9000 端口，可通过 imagePort 自定义
企业版镜像：必须指定 registryId，否则部署会失败
代码下载限制：镜像部署的函数无法使用 tcb fn code download 下载代码
scf_bootstrap 跳过：镜像部署时会跳过 Web 函数的 scf_bootstrap 检查

拉取函数配置

使用 tcb config pull fn 命令可以从云端拉取已部署云函数的配置,并保存到本地配置文件:

tcb config pull fn [name...] [options]

命令参数:

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

命令行为说明:

如果云函数存在,从云端拉取完整配置
如果云函数不存在,会询问是否从本地项目推测配置
如果目标配置文件已存在,会智能合并:
- 同名函数配置会询问是否更新
- 不同名函数配置会追加到 functions 数组

使用示例:

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

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

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

# 输出到控制台
tcb config pull fn func1 func2 --stdout

# 自动确认模式（跳过交互确认）
tcb config pull fn --all --yes

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

更新函数配置

使用 tcb config update fn 命令可以更新已部署云函数的运行时配置。

基本用法

# 更新指定函数的配置（从配置文件读取）
tcb config update fn <functionName>

# 更新配置文件中所有函数的配置
tcb config update fn --all

命令参数

参数	说明	必填
`fn`	模块名称，指定操作云函数配置	是
`<functionName>`	云函数名称	否
`--all`	更新配置文件中所有函数的配置	否
`-e, --env-id <envId>`	环境 Id	否
`--timeout <timeout>`	函数超时时间（秒），范围 1-900	否
`--memory <memory>`	函数内存大小（MB），范围 64-3072	否
`--env <key=value>`	设置环境变量，可多次使用	否
`--env-mode <mode>`	环境变量更新模式：`merge`（合并）或 `overwrite`（覆盖）	否
`--yes`	跳过交互确认，直接执行	否

通过 CLI 参数快速更新

除了从配置文件读取，还可以直接通过 CLI 参数更新单个配置项：

# 更新超时时间
tcb config update fn myFunc --timeout 60 -e envId --yes

# 更新内存大小
tcb config update fn myFunc --memory 512 -e envId --yes

# 更新环境变量（合并模式，保留原有变量）
tcb config update fn myFunc --env DB_HOST=127.0.0.1 --env-mode merge -e envId --yes

# 更新环境变量（覆盖模式，替换所有变量）
tcb config update fn myFunc --env DB_HOST=127.0.0.1 --env-mode overwrite -e envId --yes

# 同时更新多个配置
tcb config update fn myFunc --timeout 30 --memory 256 --env NODE_ENV=production -e envId --yes

配置优先级

配置更新遵循以下优先级（从高到低）：

CLI 参数 > 配置文件 > 云端现有配置

注意

使用 --env-mode overwrite 时，配置文件中的环境变量会完全覆盖云端配置
使用 --env-mode merge 时，只更新指定的环境变量，保留其他变量
建议在自动化脚本中添加 --yes 参数跳过交互确认

使用示例

# 从配置文件更新 app 函数的配置
tcb config update fn app

# 更新所有函数的配置（跳过确认）
tcb config update fn --all --yes

# 快速更新单个配置项
tcb config update fn app --timeout 60 --yes

对比函数配置

使用 tcb config diff fn 命令可以对比本地配置文件与云端函数配置的差异。

基本用法

# 对比指定函数的配置
tcb config diff fn <functionName>

# 对比配置文件中所有函数的配置
tcb config diff fn --all

命令参数

参数	说明	必填
`fn`	模块名称，指定操作云函数配置	是
`<functionName>`	云函数名称	否
`--all`	对比配置文件中所有函数的配置	否
`-e, --env-id <envId>`	环境 Id	否

使用示例

# 对比单个函数的配置差异
tcb config diff fn myFunc -e envId

# 对比所有函数的配置差异
tcb config diff fn --all -e envId

输出示例

命令会以表格形式输出配置对比结果：

函数 [myFunc] 配置对比

| 配置项     | 云端值  | 本地值  | 变更 |
|------------|---------|---------|------|
| timeout    | 5       | 60      | ~    |
| memorySize | 256     | 512     | ~    |
| role       | -       | SCF_CLS | ~    |
| 函数类型   | HTTP    | HTTP    |      |

变更标记说明：

~：配置项有变更
空：配置项无变更

使用场景

部署前检查配置变更，避免意外覆盖
排查配置不一致问题
代码审查时确认配置变更

完整配置示例

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

{
  // 环境 ID（必填）
  "envId": "dev-xxxx",

  // 云函数根目录，默认为 ./functions
  "functionRoot": "./functions",

  // 云函数配置数组
  "functions": [
    // ========== 普通云函数（事件触发）==========
    {
      "name": "app",                    // 函数名称（必填）
      "handler": "index.main",          // 入口函数，格式：文件名.函数名
      "timeout": 5,                     // 超时时间（秒），范围 1-900
      "runtime": "Nodejs18.15",         // 运行时环境
      "memorySize": 256,                // 内存大小（MB），范围 64-3072
      "installDependency": true,        // 云端自动安装依赖（仅 Node.js）

      // 环境变量（部署时完全覆盖云端配置）
      "envVariables": {
        "NODE_ENV": "production",
        "DB_HOST": "localhost"
      },

      // VPC 私有网络配置
      "vpc": {
        "vpcId": "vpc-xxx",
        "subnetId": "subnet-xxx"
      },

      // 定时触发器配置
      "triggers": [
        {
          "name": "dailyTask",          // 触发器名称
          "type": "timer",              // 类型：timer（定时触发）
          "config": "0 0 2 * * * *"     // Cron 表达式：每天凌晨 2 点
        }
      ],

      // 部署时忽略的文件
      "ignore": [
        "*.md",
        ".git",
        "node_modules",
        "node_modules/**/*",
        "test/**/*"
      ]
    },

    // ========== HTTP 云函数（Web 服务）==========
    {
      "name": "webApi",
      "type": "HTTP",                   // HTTP 函数必须设置为 "HTTP"
      "handler": "index.main",
      "timeout": 60,
      "runtime": "Nodejs18.15",
      "memorySize": 512,

      // 单实例多并发配置（仅 HTTP 函数支持）
      "instanceConcurrencyConfig": {
        "maxConcurrency": 40,           // 单实例最大并发数，范围 2-100
        "dynamicEnabled": "FALSE"       // FALSE：静态并发
      },

      "envVariables": {
        "NODE_ENV": "production"
      }
    },

    // ========== WebSocket 函数 ==========
    {
      "name": "wsHandler",
      "type": "HTTP",
      "handler": "index.main",
      "timeout": 900,
      "runtime": "Nodejs18.15",
      "memorySize": 256,
      "protocolType": "WS",             // 启用 WebSocket 协议
      "protocolParams": {
        "wsParams": {
          "idleTimeOut": 600            // 空闲超时（秒），范围 10-7200
        }
      }
    },

    // ========== 镜像部署函数 ==========
    {
      "name": "imageFunc",
      "type": "HTTP",
      "timeout": 60,
      "memorySize": 1024,

      // 镜像配置（镜像部署不需要 handler 和 runtime）
      "imageConfig": {
        "imageType": "personal",        // personal：个人版 | enterprise：企业版
        "imageUri": "<访问域名>/your-namespace/your-image:v1.0.0",
        "imagePort": 9000               // 容器监听端口，默认 9000
      },

      // 日志配置（镜像部署需要手动配置）
      "role": "SCF_CLSWriteOnly",
      "clsLogsetId": "your-logset-id",
      "clsTopicId": "your-topic-id"
    }
  ]
}

配置说明

jsonc 格式支持注释，实际使用时需要移除注释或使用标准 JSON 格式
HTTP 函数必须将 type 设置为 HTTP
环境变量部署时会完全覆盖云端配置，请确保包含所有需要的变量

重要提示

环境变量覆盖规则

部署时 envVariables 配置会完全覆盖云端已有的环境变量配置,而非增量合并。

示例场景:

云端已配置环境变量: {DB_HOST: "xxx", API_KEY: "xxx"}
配置文件中仅有: {DB_HOST: "yyy"}
部署后云端环境变量变为: {DB_HOST: "yyy"} (API_KEY 被删除)

建议做法: 如果在控制台手动配置了环境变量,请确保在 cloudbaserc.json 中也包含这些配置,否则部署后会丢失。

快速示例​

配置项详解​

基础配置项​

代码和依赖配置​

高级配置​

运行时环境​

触发器配置​

VPC 配置​

WebSocket 配置​

并发配置​

镜像配置​

拉取函数配置​

更新函数配置​

基本用法​

命令参数​

通过 CLI 参数快速更新​

配置优先级​

使用示例​

对比函数配置​

基本用法​

命令参数​

使用示例​

输出示例​

完整配置示例​

重要提示​

环境变量覆盖规则​

快速示例

配置项详解

基础配置项

代码和依赖配置

高级配置

运行时环境

触发器配置

VPC 配置

WebSocket 配置

并发配置

镜像配置

拉取函数配置

更新函数配置

基本用法

命令参数

通过 CLI 参数快速更新

配置优先级

使用示例

对比函数配置

基本用法

命令参数

使用示例

输出示例

完整配置示例

重要提示

环境变量覆盖规则