部署云函数

使用 tcb fn deploy 命令可以快速部署云函数到云开发环境。

tcb fn deploy [options] [name]

命令参数

参数	说明	必填
`-e, --env-id <envId>`	环境 Id	否
`--httpFn`	部署为 HTTP 云函数	否
`--ws`	部署 HTTP 云函数时启用 WebSocket 协议	否
`--code-secret <codeSecret>`	传入此参数将保护代码，格式为 36 位大小写字母和数字	否
`--force`	如果存在同名函数，上传后覆盖同名函数	否
`--path <path>`	自动创建 HTTP 网关访问路径	否
`--dir <dir>`	指定云函数的文件夹路径	否
`--all`	部署配置文件中包含的全部云函数	否
`--deployMode <deployMode>`	上传模式：`cos`（默认推荐）、`zip`（不推荐，限 1.5 MB）、`image`（镜像）	否
`--yes`	跳过交互确认，直接执行部署	否
`--install-dependency <boolean>`	是否云端自动安装依赖：`true` 开启、`false` 关闭（覆盖配置文件，默认跟随配置）	否
`--metadata-file <path>`	将本次部署的资源元数据（名称/资源类型/动作/版本引用/部署时间/产出命令）写入指定 JSON 文件，已存在则按资源合并	否
`-h, --help`	查看命令帮助信息	否

基本用法

方式一：使用配置文件（推荐）

在包含 cloudbaserc.json 配置文件的项目目录下执行：

# 部署指定函数
tcb fn deploy <functionName>

# 部署配置文件中的所有函数
tcb fn deploy --all

# 关闭云端安装依赖，本地 node_modules 随包上传
tcb fn deploy <functionName> --install-dependency false

# 显式开启云端自动安装依赖
tcb fn deploy <functionName> --install-dependency true

方式二：从当前目录部署

在函数代码目录下（包含 package.json），无需配置文件即可直接部署：

cd my-function
tcb fn deploy

CLI 会自动从 package.json 读取函数名称，并使用默认配置部署。

部署 HTTP 函数

添加 --httpFn 参数即可部署为 HTTP 函数：

tcb fn deploy <functionName> --httpFn

使用示例

标准工作空间部署

project/
├── cloudbaserc.json
└── functions/
    └── hello/
        ├── index.js
        └── package.json

tcb fn deploy hello

自定义函数目录

// cloudbaserc.json
{
  "envId": "your-env-id",
  "functionRoot": "./functions",
  "functions": [
    {
      "name": "api",
      "dir": "./src/cloud-functions/api",
      "runtime": "Nodejs20.19"
    }
  ]
}

tcb fn deploy api

命令行指定目录

tcb fn deploy hello --dir ./my-custom-path/hello

部署路径解析

部署时，CLI 按以下优先级解析函数代码路径：

--dir 参数（命令行指定）     →  最高优先级
functions[].dir（配置文件）  →  次优先级
functionRoot + 函数名        →  默认路径（functionRoot 默认为 ./functions）
当前工作目录                 →  无配置文件时的兜底

场景	配置文件	--dir	functions.dir	最终路径
标准部署	✅ 存在	❌	❌	`functionRoot/函数名`
自定义目录	✅ 存在	❌	✅ 指定	`functions.dir` 路径
命令行覆盖	✅ 存在	✅ 指定	-	`--dir` 路径
无配置文件	❌	❌	-	`当前工作目录`

注意

批量部署时（使用 --all 或不指定函数名），--dir 参数无效，会被忽略。

批量部署行为

使用 --all（或不指定函数名）批量部署时，CLI 采用 5 路并行（固定值）逐个部署配置文件中的函数，而非串行排队：

同一时刻最多 5 个函数在同时部署（创建/更新代码、更新配置、创建触发器等）
某个函数部署失败不会中断其余函数，CLI 会继续部署完所有函数，最后汇总报告失败列表并以非零退出码结束
每个函数部署完成后会以 1 秒间隔轮询云端状态直至就绪，函数数量较多时对云 API 的请求较为集中

限频提示

单账户（UIN）对云函数 API 有请求频率限制。函数数量较多（如数十个以上）、或多条流水线同时部署同一账户时，可能触发限频（RequestLimitExceeded）。限频导致的失败不会自动重试，需重新执行部署。如需更可控的并发，可改用 tcb deploy --concurrency。

与 `tcb deploy` 的批量行为对比

行为	`tcb fn deploy --all`	`tcb deploy`
并发度	固定 5 路，不可调	默认 1（串行），`--concurrency` 可调（上限 20）
失败策略	继续部署其余，最后汇总失败列表	默认 fail-fast 立即中断；`--continue-on-error` 可改为继续
适用场景	纯函数批量部署，追求吞吐	多资源编排（函数/托管/网关等），追求确定性

部署元数据文件（--metadata-file）

--metadata-file <path> 会把「本次部署实际改动了哪些资源」写入一个 JSON 文件，供平台侧（部署记录、回滚、可视化）消费：

tcb fn deploy --all --metadata-file ./deploy-metadata.json

写入发生在结果汇总之后、--json 输出之前，因此普通模式与 --json 模式都会落盘。写入失败不影响部署结论（部署已成功时只提示错误并返回非零退出码）。

文件结构：

{
  "version": 1,
  "envId": "your-env-id",
  "command": "fn deploy",
  "deployTime": "2026-09-29T02:53:12.726Z",
  "resources": [
    {
      "name": "hello",
      "resourceType": "EVENT",
      "action": "create",
      "deployedRef": "$LATEST",
      "deployedAt": "2026-09-29T02:53:12.726Z",
      "deployedBy": "fn deploy"
    }
  ]
}

字段	说明
`resourceType`	`EVENT` / `HTTP`（云函数，取自云端类型）/ `STATIC`（静态托管云应用）
`action`	`create` / `update`；镜像部署还可能返回 `replace` / `noop`；`tcb fn publish-version` 写入 `publish`
`deployedRef`	版本引用：代码包部署为 `$LATEST`，镜像部署为镜像 digest，拿不到引用时显式为 `null`
`deployedAt` / `deployedBy`	该资源最后一次部署的时间与产出命令（资源级时间线）

合并规则：

以 resourceType + name 为键字段级合并，不整体替换条目，因此同一个文件可被多条命令依次写入（例如先 tcb fn deploy 再 tcb fn publish-version）
publish 不会覆盖已有的 create / update（资源级动作归属 tcb fn deploy）
已有的 deployedRef 不会被空值覆盖（null 或空串都视为「没有引用」），避免元数据信息倒退
文件已存在但内容损坏（非法 JSON、缺少 resources 数组、条目结构不合法、schema 版本不受支持）会直接报错（错误码 METADATA_FILE_INVALID），不会静默按空文件重建

高级选项

代码加密

通过 --code-secret 参数对代码进行加密，密钥需要使用 36 位大小写字母和数字组成：

tcb fn deploy app --code-secret 7sGLwMnhgEfKmkqg2dMjB6xWk2hCxsAgGR6w

注意

启用代码加密后，将无法在小程序 IDE、腾讯云控制台中查看云函数的代码和信息。

覆盖同名函数

如果云端已存在同名函数，CLI 会提示是否覆盖。如需强制覆盖，可使用 --force 参数：

tcb fn deploy app --force

重要提示

使用 --force 参数覆盖函数时，会同时覆盖函数的配置和触发器。

跳过交互确认

在自动化脚本或 CI/CD 流程中，可以使用 --yes 参数跳过所有交互式确认：

# 部署时跳过确认
tcb fn deploy app --yes

# 批量部署跳过确认
tcb fn deploy --all --yes

# 强制覆盖并跳过确认
tcb fn deploy app --force --yes

自动化部署建议

在 CI/CD 流程中，建议始终添加 --yes 参数以避免脚本阻塞等待用户输入。

HTTP 函数

HTTP 函数是专门针对 Web 服务场景优化的云函数类型，支持标准 HTTP 请求响应模式。

部署方式（代码包 zip）

适用于纯 Node.js/Python、依赖简单的 HTTP 服务（最常用的方式）。

前置条件：HTTP 函数需要 scf_bootstrap 启动脚本来启动 Web Server，监听 9000 端口。如果未创建，CLI 会提示自动生成。

方式一：使用配置文件

在 cloudbaserc.json 中将 type 设置为 HTTP，然后执行：

cloudbaserc.json
{
  "envId": "your-env-id",
  "functions": [
    {
      "name": "webFunction",
      "type": "HTTP",
      "runtime": "Nodejs16.13",
      "handler": "index.main",
      "installDependency": true
    }
  ]
}

tcb fn deploy webFunction

方式二：使用命令行参数

tcb fn deploy <functionName> --httpFn

CLI 会自动从当前目录读取 package.json 并创建 HTTP 函数配置。

方式三：从当前目录部署

在函数代码目录下（包含 package.json 或 requirements.txt），无需指定函数名：

cd my-web-function
tcb fn deploy --httpFn

CLI 会自动从 package.json 的 name 字段读取函数名称，并按代码包方式部署为 HTTP 函数。

镜像部署（HTTP 函数支持 cloud / local / image 三种 buildStrategy）见下方镜像部署章节。

启动脚本

HTTP 函数需要 scf_bootstrap 启动脚本来启动 Web Server。如果未创建，CLI 会提示自动生成。

详细说明

关于启动脚本的完整说明（基本要求、示例模板、运行时路径、常见错误排查），请参考启动脚本。

访问配置（public / gatewayPath）

tcb fn deploy 部署 HTTP 函数时，支持读取 cloudbaserc.json 中 functions[].public 与 functions[].gatewayPath，部署完成后自动配置访问，与声明式 tcb deploy 行为一致：

{
  "functions": [
    {
      "name": "apiDemo",
      "type": "HTTP",
      "handler": "index.main",
      "public": true,
      "gatewayPath": "/api"
    }
  ]
}

字段	行为
`public: true`	自动放通匿名访问（OPA Rego），无需登录即可通过 URL 调用
`gatewayPath`	自动收敛 API 网关路由（幂等，重复部署不会产生重复路由）

仅 HTTP 函数生效；两者都未配置时不做任何额外操作。

镜像部署

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

适用场景

需要自定义运行时环境
使用 Node.js/Python 以外的语言（如 Go、Rust）
依赖特定系统库或二进制文件
需要预装大量依赖包
已有容器化应用迁移

前置条件

使用镜像部署云函数前，请确保已完成以下准备工作：

授权镜像拉取（按镜像仓库类型一次性授权）：
- 个人版：为云函数角色授权策略 QcloudAccessForSCFRoleInPullImage：点击授权
- 企业版：需配置 2 个策略（云函数角色 + 云开发角色）：
  - 为云函数角色授权策略 QcloudAccessForSCFRoleInPullImage：点击授权
  - 为云开发角色授权策略 QcloudAccessForTCBRoleInTCR：点击授权
准备镜像仓库：在腾讯云容器镜像服务 TCR 创建仓库；参考获取访问凭证和推送镜像
镜像要求：基于 Linux 的 amd64 镜像，容器内监听 9000 端口
创建日志角色（用于日志投递）：
- 在 CAM 角色控制台创建角色
- 选择腾讯云产品服务，角色载体选择 scf 和 cls
- 关联自定义策略（推荐采用共享角色 + 只写权限方案，防止跨环境日志越权）
- 记录角色名称（如 SCF_CLSWriteOnly），后续在配置文件中使用
多租户安全提示：单租户场景可使用预置策略 QcloudCLSFullAccess。如果在同一账号下管理多个租户环境，建议使用自定义策略以防止跨环境日志越权，详见日志角色权限与多租户隔离。

镜像部署地域限制

通过镜像部署云函数，个人版与企业版镜像仓库均需与函数部署地域一致，仅支持同地域（Region）下私有镜像仓库的镜像读取，不支持跨地域。

HTTP 函数镜像策略

HTTP 函数镜像部署支持 3 种 buildStrategy 策略，与 Event 函数不同，需要指定 type: HTTP：

策略	说明	关键配置项
`cloud`	CloudApp 云端流水线负责构建并推送镜像，无需本地 Docker	`buildStrategy: "cloud"`（基准）
`local`	CLI 在本地执行 `docker build` 和 `docker push`，需本机已安装 Docker	`buildStrategy: "local"` + `imageConfig.build.dockerfile`
`image`	需先手动完成下方「构建镜像 + 推送镜像」步骤，再配置 `imageUri`	`buildStrategy: "image"` + `imageConfig.imageUri`

完整配置（个人版/企业版差异、imageConfig.build.dockerfile、registryId、containerImageAccelerate 等扩展字段）见下方「镜像部署配置参考」。image 策略的完整云端操作步骤见「部署流程」。三种策略的部署命令相同：

tcb fn deploy webFunction --deployMode image

镜像部署配置参考

以下为 buildStrategy: "cloud" 策略下个人版与企业版的完整配置示例：

个人版（personal）
企业版（enterprise）

cloudbaserc.json
{
  "$schema": "https://static.cloudbase.net/cli/cloudbaserc.schema.json",
  "version": "2.1",
  "envId": "{{env.ENV_ID}}",
  "functionRoot": "functions",
  "functions": [
    {
      "name": "hello-cloud",
      "type": "HTTP",
      "protocolType": "HTTP",
      "runtime": "CustomImage",
      "buildStrategy": "cloud",
      "timeout": 15,
      "memorySize": 256,
      "imageConfig": {
        "imageType": "personal",
        "imagePort": 9000,
        "build": {
          "dockerfile": "Dockerfile",
          "namespace": "{{env.TCB_TCR_NAMESPACE}}",
          "registryCredential": {
            "username": "{{env.TCB_TCR_USERNAME}}",
            "password": "{{env.TCB_TCR_PASSWORD}}"
          }
        }
      }
    }
  ]
}

cloudbaserc.json
{
  "$schema": "https://static.cloudbase.net/cli/cloudbaserc.schema.json",
  "version": "2.1",
  "envId": "{{env.ENV_ID}}",
  "functionRoot": "functions",
  "functions": [
    {
      "name": "hello-world",
      "type": "HTTP",
      "runtime": "CustomImage",
      "buildStrategy": "cloud",
      "timeout": 15,
      "memorySize": 256,
      "imageConfig": {
        "imageType": "enterprise",
        "registryId": "{{env.REGISTRY_ID}}",
        "imagePort": 9000,
        "containerImageAccelerate": true,
        "build": {
          "dockerfile": "Dockerfile",
          "repository": "{{env.REPOSITORY}}"
        }
      }
    }
  ]
}

部署流程（仅 `image` 策略）

适用说明

以下手动构建/推送步骤仅适用于 buildStrategy: "image"。cloud / local 策略由 CloudApp 云端或 CLI 自动完成，无需手动操作。

步骤 1：构建镜像

在函数代码目录下（包含 Dockerfile），构建 Docker 镜像：

cd /path/to/your-function

# 构建镜像（必须指定 linux/amd64 平台）
docker build --platform linux/amd64 -t your-function:v1 .

重要

在 ARM 架构机器（如 M1/M2 Mac）上构建时，必须添加 --platform linux/amd64 参数，否则镜像无法在云函数环境运行。

步骤 2：推送镜像

将镜像推送到腾讯云容器镜像服务（TCR）：

# 标记镜像
docker tag [imageId] <访问域名>/your-namespace/your-function:[tag]

# 推送镜像
docker push <访问域名>/your-namespace/your-function:[tag]

步骤 3：配置并部署

在 cloudbaserc.json 中配置 imageConfig：

{
  "envId": "your-env-id",
  "functions": [
    {
      "name": "your-function",
      "imageConfig": {
        "imageType": "personal",
        "imageUri": "<访问域名>/your-namespace/your-function:v1"
      },
      "role": "SCF_CLSFullAccess",
      "clsLogsetId": "your-logset-id",
      "clsTopicId": "your-topic-id"
    }
  ]
}

日志配置

镜像部署的云函数需要手动配置日志投递：

在日志服务控制台创建日志集和日志主题，获取 clsLogsetId 和 clsTopicId
在前置条件中创建的日志角色名称填入 role 字段

执行部署：

tcb fn deploy <functionName> --deployMode image

配置详情

完整的镜像配置项说明，请参考镜像配置。

配置文件

云函数的配置通过 cloudbaserc.json 文件管理，包括函数名称、运行时、超时时间、环境变量等。

配置详情

完整的配置项说明和示例，请参考云函数配置文件。

注意事项

函数类型不可变更

已部署的函数类型（普通函数/HTTP 函数）不支持变更。如需变更类型，请先删除原函数后重新部署。

环境变量更新规则

@cloudbase/cli 2.12.0 及以上版本：部署时支持选择增量更新或覆盖更新环境变量
@cloudbase/cli 2.12.0 以下版本：cloudbaserc.json 中的环境变量配置会完全覆盖线上已配置的环境变量

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

部署云函数

命令参数

基本用法

方式一：使用配置文件（推荐）

方式二：从当前目录部署

部署 HTTP 函数

使用示例

标准工作空间部署

自定义函数目录

命令行指定目录

部署路径解析

批量部署行为

与 `tcb deploy` 的批量行为对比

部署元数据文件（--metadata-file）

高级选项

代码加密

覆盖同名函数

跳过交互确认

HTTP 函数

部署方式（代码包 zip）

方式一：使用配置文件

方式二：使用命令行参数

方式三：从当前目录部署

启动脚本

访问配置（public / gatewayPath）

相关指南

镜像部署

适用场景

前置条件

HTTP 函数镜像策略

镜像部署配置参考

部署流程（仅 `image` 策略）

步骤 1：构建镜像

步骤 2：推送镜像

步骤 3：配置并部署

配置文件

注意事项

相关文档

命令参数​

基本用法​

方式一：使用配置文件（推荐）​

方式二：从当前目录部署​

部署 HTTP 函数​

使用示例​

标准工作空间部署​

自定义函数目录​

命令行指定目录​

部署路径解析​

批量部署行为​

与 tcb deploy 的批量行为对比​

部署元数据文件（--metadata-file）​

高级选项​

代码加密​

覆盖同名函数​

跳过交互确认​

HTTP 函数​

部署方式（代码包 zip）​

方式一：使用配置文件​

方式二：使用命令行参数​

方式三：从当前目录部署​

启动脚本​

访问配置（public / gatewayPath）​

相关指南​

镜像部署​

适用场景​

前置条件​

HTTP 函数镜像策略​

镜像部署配置参考​

部署流程（仅 image 策略）​

步骤 1：构建镜像​

步骤 2：推送镜像​

步骤 3：配置并部署​

配置文件​

注意事项​

相关文档​

命令参数

基本用法

方式一：使用配置文件（推荐）

方式二：从当前目录部署

部署 HTTP 函数

使用示例

标准工作空间部署

自定义函数目录

命令行指定目录

部署路径解析

批量部署行为

与 `tcb deploy` 的批量行为对比

部署元数据文件（--metadata-file）

高级选项

代码加密

覆盖同名函数

跳过交互确认

HTTP 函数

部署方式（代码包 zip）

方式一：使用配置文件

方式二：使用命令行参数

方式三：从当前目录部署

启动脚本

访问配置（public / gatewayPath）

相关指南

镜像部署

适用场景

前置条件

HTTP 函数镜像策略

镜像部署配置参考

部署流程（仅 `image` 策略）

步骤 1：构建镜像

步骤 2：推送镜像

步骤 3：配置并部署

配置文件

注意事项

相关文档