tcb fn deploy

部署云函数到云开发环境，首次部署时创建函数。

语法

tcb fn deploy [options] [name]

参数

参数	必填	说明	默认值
[name]	否	函数名称，不传时部署配置文件中的全部函数	—
-e, --env-id <envId>	否	环境 ID	取当前默认环境
--dir <dir>	否	指定函数的文件夹路径	—
--cwd <dir>	否	函数代码目录，用于在其他目录执行部署	当前目录
--all	否	部署配置文件中的全部函数	—
--deployMode <deployMode>	否	上传模式：cos、zip（上限 1.5 MB）、image	cos
--install-dependency <boolean>	否	是否在云端自动安装依赖，覆盖配置文件	跟随配置文件
--httpFn	否	部署为 HTTP 函数	—
--ws	否	部署 HTTP 函数时启用 WebSocket	—
--path <path>	否	自动创建 HTTP 网关访问路径	—
--code-secret <codeSecret>	否	加密代码，取值为 36 位大小写字母和数字	—
--force	否	同名函数存在时直接覆盖，同时覆盖配置与触发器	—
--yes	否	跳过交互确认	—
--metadata-file <path>	否	将本次部署的资源元数据写入 JSON 文件	—

部署类型

类型	适用场景	入口
代码包	常规函数与 HTTP 函数，依赖简单	默认方式，见示例
HTTP 函数	Web 服务，需要 scf_bootstrap 启动服务	--httpFn 或配置 type: HTTP，见 HTTP 函数部署
镜像	自定义运行时、非 Node.js 与 Python 语言、依赖系统库	--deployMode image，见镜像部署

示例

使用配置文件

在包含 cloudbaserc.json 的项目目录下执行：

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

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

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

# 覆盖同名函数并跳过确认，适合 CI/CD
tcb fn deploy <functionName> --force --yes

# 加密代码
tcb fn deploy app --code-secret 7sGLwMnhgEfKmkqg2dMjB6xWk2hCxsAgGR6w

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

从当前目录

函数代码目录包含 package.json 时，可以不依赖配置文件直接部署。CLI 从 package.json 读取函数名称并使用默认配置。

cd my-function
tcb fn deploy

# 或保持当前目录，用 --cwd 指向函数目录
tcb fn deploy --cwd ./my-function

指定代码目录

用命令行参数临时覆盖配置文件中的路径：

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

优先级的完整规则见部署路径解析。

部署路径解析

CLI 按以下顺序解析函数代码路径，命中即停止：

1. --dir 参数（命令行指定）
2. functions[].dir（配置文件）
3. functionRoot + 函数名（functionRoot 默认为 ./functions）
4. 项目目录（无配置文件时的兜底）

--dir 相对当前目录解析，functions[].dir 与 functionRoot 相对项目目录解析。项目目录见 全局选项。

场景	最终路径
有配置文件，未指定目录	functionRoot/函数名
配置文件设置了 functions[].dir	functions.dir
命令行传了 --dir	--dir
无配置文件	项目目录

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

批量部署

使用 --all 或不指定函数名时，CLI 以固定 5 路并行逐个部署配置文件中的函数：

• 同一时刻最多 5 个函数在部署，包括更新代码、更新配置和创建触发器。
• 单个函数失败不会中断其余函数，CLI 部署完所有函数后汇总失败列表，并以非零退出码结束。
• 每个函数部署完成后以 1 秒间隔轮询云端状态直至就绪。

单账户对云函数 API 有频率限制。函数数量较多，或多条流水线同时部署同一账户时，可能触发 RequestLimitExceeded。限频失败不会自动重试，需要重新执行部署。

与声明式部署的差异：

行为	tcb fn deploy --all	tcb deploy
并发度	固定 5 路，不可调	默认 1，--concurrency 可调至 20
失败策略	继续部署，最后汇总失败列表	默认立即中断，--continue-on-error 可继续
适用场景	纯函数批量部署	多资源编排

需要可控并发时，改用 tcb deploy --concurrency。

元数据文件

--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；publish-version 写入 publish
deployedRef	版本引用：代码包为 $LATEST，镜像为镜像 digest，无法获取时为 null
deployedAt / deployedBy	该资源最后一次部署的时间与产出命令

合并规则：

• 以 resourceType + name 为键做字段级合并，不整体替换条目，同一文件可被多条命令依次写入。
• publish 不覆盖已有的 create / update。
• 已有的 deployedRef 不被空值覆盖。
• 文件内容损坏时报错 METADATA_FILE_INVALID，不会按空文件重建。

HTTP 函数部署

HTTP 函数针对 Web 服务场景，支持标准 HTTP 请求响应模式。需要 scf_bootstrap 脚本启动 Web Server 并监听 9000 端口，脚本不存在时 CLI 提示自动生成。

指定方式

方式	命令	说明
配置文件	tcb fn deploy webFunction	在 cloudbaserc.json 中设置 type: HTTP
命令行参数	tcb fn deploy <name> --httpFn	从当前目录的 package.json 生成配置
当前目录	cd my-web-function && tcb fn deploy --httpFn	从 package.json 的 name 字段读取函数名

配置文件方式：

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

访问配置

tcb fn deploy 读取 functions[].public 与 functions[].gatewayPath，部署完成后自动配置访问。

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

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

两个字段都只对 HTTP 函数生效，未配置时不做额外操作。

启动脚本的完整说明见 启动脚本，项目结构见 HTTP 函数开发指南。

镜像部署

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

前置条件

1. 授权镜像拉取，按镜像仓库类型一次性授权：
   • 个人版：为云函数角色授权 QcloudAccessForSCFRoleInPullImage，前往授权。
   • 企业版：云函数角色授权 QcloudAccessForSCFRoleInPullImage，前往授权；云开发角色授权 QcloudAccessForTCBRoleInTCR，前往授权。
2. 准备镜像仓库：在 容器镜像服务 TCR 创建仓库，参考 获取访问凭证 与 推送镜像。
3. 镜像要求：基于 Linux 的 amd64 镜像，容器内监听 9000 端口。
4. 创建日志角色：在 CAM 角色控制台 创建角色，角色载体选择 scf 和 cls，关联自定义策略，记录角色名称。

镜像仓库必须与函数部署地域一致，只支持同地域私有仓库的镜像。

单租户可使用预置策略 QcloudCLSFullAccess。同一账号管理多个租户环境时，使用自定义策略防止跨环境日志越权，详见日志角色权限与多租户隔离。

构建策略

HTTP 函数镜像部署支持 3 种 buildStrategy，同时需要指定 type: HTTP。

策略	说明	关键配置
cloud	云端流水线构建并推送镜像，无需本地 Docker	buildStrategy: "cloud"
local	CLI 在本地执行 docker build 和 docker push，需安装 Docker	buildStrategy: "local" + imageConfig.build.dockerfile
image	手动构建推送后配置 imageUri	buildStrategy: "image" + imageConfig.imageUri

三种策略的部署命令相同：

tcb fn deploy webFunction --deployMode image

配置示例

个人版（personal）

cloudbaserc.json

{
  "$schema": "https://static.cloudbase.net/cli/cloudbaserc.schema.json",
  "envId": "{{env.ENV_ID}}",
  "functionRoot": "functions",
  "functions": [
    {
      "name": "hello-cloud",
      "type": "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}}"
          }
        }
      }
    }
  ]
}

企业版（enterprise）

cloudbaserc.json

{
  "$schema": "https://static.cloudbase.net/cli/cloudbaserc.schema.json",
  "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}}"
        }
      }
    }
  ]
}

完整字段说明见 镜像配置。

手动构建与推送

仅 buildStrategy: "image" 需要手动执行。cloud 和 local 由云端或 CLI 完成。

构建镜像，必须指定 linux/amd64：

cd /path/to/your-function
docker build --platform linux/amd64 -t your-function:v1 .

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

推送镜像：

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

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

配置 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"
    }
  ]
}

tcb fn deploy <functionName> --deployMode image

镜像部署的函数需要手动配置日志投递：在 日志服务控制台 创建日志集和日志主题，填入 clsLogsetId 与 clsTopicId，role 填前置条件中创建的日志角色名称。

注意事项

• 已部署的函数类型（普通函数或 HTTP 函数）不支持变更，需要先删除原函数再重新部署。
• CLI 2.12.0 及以上版本部署时可以选择增量更新或覆盖更新环境变量。
• CLI 2.12.0 以下版本部署时，配置文件中的环境变量完全覆盖线上配置。在控制台手动配置过环境变量的项目需要同步到配置文件，否则部署后丢失。

相关文档

• 函数代码：只更新代码时使用 tcb fn code update
• 版本管理：发布不可变版本
• 声明式部署：多资源统一编排
• 函数配置：配置文件字段
• Access Token 获取