配置文件-云函数

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

本文只说明 functions 配置字段；如何执行部署请参考部署云函数，如何拉取、更新、对比配置请参考配置操作。

配置扁平化

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

字段速查

functions 数组项的全部配置字段按分组归纳如下,点击分组名可跳转到对应章节:

配置分组	包含字段
基础配置项	`functionRoot`、`name`、`type`、`dir`、`handler`、`runtime`、`timeout`、`memorySize`、`protocolType`、`protocolParams`、`instanceConcurrencyConfig`、`imageConfig`、`buildStrategy`
代码和依赖配置	`ignore`、`installDependency`、`codeSecret`
高级配置	`envVariables`、`vpc`、`triggers`、`params`、`role`、`clsLogsetId`、`clsTopicId`、`public`、`gatewayPath`
运行时环境	支持的运行时版本列表
触发器配置	`name`、`type`、`config`
VPC 配置	`vpcId`、`subnetId`
WebSocket 配置	`wsParams.idleTimeOut`
并发配置	`maxConcurrency`、`dynamicEnabled`
镜像配置	`imageType`、`imageUri`、`registryId`、`imagePort`、`entryPoint`、`commandList`、`argsList`、`containerImageAccelerate`

快速示例

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

{
  "envId": "dev-xxxx",
  "functionRoot": "./functions",
  "functions": [
    {
      "name": "app",
      "timeout": 5,
      "runtime": "Nodejs20.19",
      "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	`Nodejs20.19`	运行时环境,详见运行时环境
`timeout`	否	Number	5	函数超时时间,取值范围 1-900 秒
`memorySize`	否	Number	256	函数内存大小(MB),取值范围 64-3072
`protocolType`	否	String	-	HTTP 函数支持的访问协议,当前支持 WebSocket 协议,值为 `WS`
`protocolParams`	否	Object	-	协议参数配置,详见 WebSocket 配置
`instanceConcurrencyConfig`	否	Object	-	实例并发配置,详见并发配置
`imageConfig`	否	Object	-	镜像部署配置,详见镜像配置
`buildStrategy`	否	String	`zip`	HTTP 函数部署策略（声明式部署），可选值: `zip`(代码包)/`image`(现有镜像)/`cloud`(云端构建镜像)/`local`(本地构建镜像)，详见镜像配置

代码和依赖配置

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

高级配置

配置项	必填	类型	默认值	描述
`envVariables`	否	Object	-	环境变量键值对,部署时的更新行为取决于 CLI 版本,详见环境变量更新规则
`vpc`	否	Object	-	私有网络配置,详见VPC 配置
`triggers`	否	Array	-	触发器配置,详见触发器配置
`params`	否	Object	-	CLI 调用云函数时的默认入参
`role`	否	String	-	函数绑定的角色名称，用于日志投递等场景
`clsLogsetId`	否	String	-	CLS 日志集 ID，镜像部署时需要手动配置
`clsTopicId`	否	String	-	CLS 日志主题 ID，镜像部署时需要手动配置
`public`	否	Boolean	`false`	是否允许匿名访问（仅 HTTP 函数），为 `true` 时部署后自动放通匿名访问（OPA Rego），无需登录即可通过 URL 调用
`gatewayPath`	否	String	-	网关路径（仅 HTTP 函数，以 `/` 开头），部署后自动收敛 API 网关路由，与声明式 `gateway.routes` 等效

运行时环境

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

Node.js 运行时

Nodejs24.11 (公测中)
Nodejs22.21 (公测中)
Nodejs20.19 (推荐)
Nodejs18.15
Nodejs16.13

其他语言运行时

Php8.0
Php7.4
Python3.11
Python3.10
Python3.9
Python3.7
Go1
Java11

完整的运行环境说明，请参阅运行环境支持。

运行时说明

Node.js 项目默认使用 Nodejs20.19 运行时,可以省略 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 检查

完整配置示例

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

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

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

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

      // 环境变量（部署时的更新行为取决于 CLI 版本，详见「环境变量更新规则」）
      "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": "Nodejs20.19",
      "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": "Nodejs20.19",
      "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
环境变量部署时的更新行为取决于 CLI 版本，请参见「环境变量更新规则」章节

重要提示

环境变量更新规则

部署时 envVariables 配置对环境变量的更新行为取决于 CLI 版本：

@cloudbase/cli 2.12.0 及以上版本

部署时支持选择增量更新（merge）或覆盖更新（overwrite）环境变量。

@cloudbase/cli 2.12.0 以下版本

cloudbaserc.json 中的环境变量配置会完全覆盖线上已配置的环境变量,而非增量合并。

重要

如果您使用的是 2.12.0 以下版本,且在控制台中手动配置了环境变量,请确保在 cloudbaserc.json 中也包含这些配置,否则部署后原有环境变量将会丢失。

覆盖场景示例（2.12.0 以下版本）:

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

字段速查​

快速示例​

配置项详解​

基础配置项​

代码和依赖配置​

高级配置​

运行时环境​

触发器配置​

VPC 配置​

WebSocket 配置​

并发配置​

镜像配置​

完整配置示例​

重要提示​

环境变量更新规则​

字段速查

快速示例

配置项详解

基础配置项

代码和依赖配置

高级配置

运行时环境

触发器配置

VPC 配置

WebSocket 配置

并发配置

镜像配置

完整配置示例

重要提示

环境变量更新规则