部署云函数

使用 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	跳过交互确认，直接执行部署	否
-h, --help	查看命令帮助信息	否

基本用法

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

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

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

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

方式二：从当前目录部署

在函数代码目录下（包含 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": "Nodejs18.15"
    }
  ]
}

tcb fn deploy api

命令行指定目录

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

部署路径解析

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

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

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

注意

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

高级选项

代码加密

通过 --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 请求响应模式。

部署方式

方式一：使用配置文件

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

tcb fn deploy webFunction

方式二：使用命令行参数

tcb fn deploy <functionName> --httpFn

方式三：从当前目录部署

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

启动脚本

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

详细说明

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

相关指南

• HTTP 函数项目结构和编写指南
• 云函数调用方式

镜像部署

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

适用场景

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

前置条件

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

1. 授权镜像拉取：为云函数角色授权策略 QcloudAccessForSCFRoleInPullImage，一次性操作：点击授权

2. 准备镜像仓库：在 腾讯云容器镜像服务 TCR 创建仓库；参考 获取访问凭证 和 推送镜像

3. 镜像要求：基于 Linux 的 amd64 镜像，容器内监听 9000 端口

4. 创建日志角色（用于日志投递）：

   • 在 CAM 角色控制台 创建角色
   • 选择腾讯云产品服务，角色载体选择 scf 和 cls
   • 关联自定义策略（推荐采用共享角色 + 只写权限方案，防止跨环境日志越权）
   • 记录角色名称（如 SCF_CLSWriteOnly），后续在配置文件中使用

   多租户安全提示：单租户场景可使用预置策略 QcloudCLSFullAccess。如果在同一账号下管理多个租户环境，建议使用自定义策略以防止跨环境日志越权，详见日志角色权限与多租户隔离。

部署流程

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

日志配置

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

1. 在 日志服务控制台 创建日志集和日志主题，获取 clsLogsetId 和 clsTopicId
2. 在前置条件中创建的日志角色名称填入 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 函数开发指南
• 云函数配置
• Access Token 获取