跳到主要内容

编写 HTTP 云函数

「HTTP 云函数」是专为 Web 服务场景设计的云函数类型，提供了原生 HTTP 支持、实时通信能力和多函数路由等特性。

💡 关于基础能力：本文聚焦 HTTP 云函数的特有能力（HTTP 处理、SSE、WebSocket、函数路由等）。如需了解云函数的通用能力（依赖安装、环境变量、时区处理等），请参考 编写普通云函数。

快速开始​

第一步：创建函数入口文件​

创建 index.js 作为 HTTP 函数入口文件：

exports.main = function (event, context) {
  return `Hello world!`;
};

第二步：创建启动脚本（必需）​

在项目根目录创建 scf_bootstrap 文件（无扩展名），内容为启动项目的命令：

#!/bin/bash
node index.js

启动脚本详情请参考：启动文件说明

项目结构​

完整的项目目录结构如下：

my-web-function/
├── scf_bootstrap          # 启动脚本（必需，无扩展名）
├── package.json           # 项目配置
├── index.js               # 函数入口文件
└── node_modules/          # 依赖包（npm install 后生成）

参考资源：

💡 提示：HTTP 云函数支持「函数路由」功能，允许多个子函数运行在同一个实例上。详见 HTTP 云函数路由。

函数结构与参数​

HTTP 云函数支持直接使用 web 相关框架来进行开发，例如：Nodejs 环境下的 Express、Koa、NestJS，或 Python 环境下的 Flask、Django 等，或其他各语言的web框架。

调用云开发资源（SDK 鉴权）​

在 HTTP 云函数中通过 SDK（@cloudbase/js-sdk 或 @cloudbase/node-sdk）访问数据库、云存储等云开发资源时，需要特别注意鉴权方式：

必须显式配置鉴权参数

与普通事件云函数不同，HTTP 云函数的运行环境不会注入 TENCENTCLOUD_SECRETID / TENCENTCLOUD_SECRETKEY 鉴权环境变量，SDK 无法自动获取默认凭证。不显式配置鉴权会导致 getCredential failed / secretId or secretKey not found 等错误，所有接口调用失败。

在 HTTP 云函数中初始化 SDK 时必须显式指定以下任一鉴权方式：

const cloudbase = require("@cloudbase/js-sdk");

// 方式一（推荐）：在函数环境变量中配置 CLOUDBASE_APIKEY，传入 accessKey
const app = cloudbase.init({
  env: "your-env-id",
  accessKey: process.env.CLOUDBASE_APIKEY,
});

// 方式二：显式传入腾讯云密钥对
// const app = cloudbase.init({
//   env: "your-env-id",
//   secretId: "xxx",
//   secretKey: "xxx",
// });

详细鉴权方式说明请参考 JS SDK 初始化 - Node.js 端鉴权。

函数路由​

HTTP云函数支持web框架，因此可以通过对应的web框架进行实现多路由

也可以基于 @cloudbase/functions-framework 框架实现。它支持将一个大函数拆分成多个子函数，并通过请求路径将不同的请求路由到不同的处理函数。

请参考：HTTP 云函数路由

实时通信能力​

HTTP 云函数提供两种实时通信方式：「SSE（Server-Sent Events）」和「WebSocket」。

SSE（Server-Sent Events）​

「SSE」是一种基于 HTTP 的服务端推送技术，支持单向实时数据流传输（服务端 → 客户端）。

核心特点：

  • 基于 HTTP 协议，兼容性好，默认支持无需配置
  • 客户端自动重连
  • 实现简单，资源占用低
  • 适合 AI 对话流式输出、实时日志、进度更新等场景

详细文档：完整的 SSE 使用指南、消息格式规范、常见问题解决，请参考 SSE 协议支持。

WebSocket​

「WebSocket」是一种全双工通信协议，支持双向实时通信（服务端 ↔ 客户端）。

核心特点：

  • 双向实时通信，持久连接，低延迟
  • 需要在控制台开启 WebSocket 协议支持
  • 服务器必须监听 9000 端口
  • 适合实时聊天、协作编辑、游戏服务器等场景

详细文档：完整的 WebSocket 使用指南、控制台配置步骤、使用限制、常见问题解决，请参考 WebSocket 协议支持。

技术选型对比​

特性SSEWebSocket
通信方式单向（服务端→客户端）双向（服务端↔客户端）
协议HTTPWebSocket 协议
实现复杂度简单相对复杂
配置要求无需配置需控制台开启
自动重连是否（需手动实现）
适用场景单向数据推送实时双向通信

选择建议：

  • 只需服务端推送数据（如 AI 对话、日志、进度）→ 选择 SSE
  • 需要双向实时通信（如聊天、协作、游戏）→ 选择 WebSocket

使用 TypeScript 编写函数代码​

类型定义安装​

npm install @cloudbase/functions-typings@v-1

基本类型定义​

import { TcbEventFunction } from "@cloudbase/functions-typings";

TcbEventFunction 是一个泛型类型：

TcbEventFunction<EventT = unknown, ResultT extends ReturnT = void>
  • EventT：定义 event 参数类型
  • ResultT：定义函数返回值类型

定义 event 参数类型​

JSON 请求体：

type JsonEvent = { a: number; b: string; c: boolean };

export const main: TcbEventFunction<JsonEvent> = function (event, context) {
  event.a; // number
  event.b; // string
};

FormData 文件上传：

import { TcbEventFunction, File } from "@cloudbase/functions-typings";

type FormEvent = { str: string; file: File };

export const main: TcbEventFunction<FormEvent> = function (event, context) {
  event.str;
  event.file.filepath;
};

定义返回值类型​

普通响应：

export const main: TcbEventFunction<void, string> = function (event, context) {
  return "done.";
};

集成响应：

import {
  TcbEventFunction,
  IntegrationResponse,
} from "@cloudbase/functions-typings";

export const main: TcbEventFunction<
  void,
  IntegrationResponse<string>
> = function (event, context) {
  return {
    statusCode: 200,
    headers: {},
    body: "Hello world",
  };
};

异步函数：

export const main: TcbEventFunction<void, Promise<string>> = async function (
  event,
  context,
) {
  return new Promise((resolve) => {
    setImmediate(() => {
      resolve("done.");
    });
  });
};

完整示例​

import {
  TcbEventFunction,
  File,
  IntegrationResponse,
} from "@cloudbase/functions-typings";

// GET 无请求体
export const main: TcbEventFunction = function (event, context) {};

// JSON 请求体
type JsonEvent = { a: number; b: string };
export const main: TcbEventFunction<JsonEvent> = function (event, context) {
  event.a;
  event.b;
};

// FormData 上传
type FormEvent = { str: string; file: File };
export const main: TcbEventFunction<FormEvent> = function (event, context) {
  event.str;
  event.file.filepath;
};

// 二进制流
export const main: TcbEventFunction<Buffer> = function (event, context) {
  event.byteLength;
};

// 访问 Context 信息
export const main: TcbEventFunction<void, void> = function (event, context) {
  context.extendedContext?.envId;
  context.extendedContext?.userId;
};

// 普通响应
export const main: TcbEventFunction<void, string> = function (event, context) {
  return "done.";
};

// 集成响应
export const main: TcbEventFunction<
  void,
  IntegrationResponse<string>
> = function (event, context) {
  return {
    statusCode: 200,
    headers: {},
    body: "",
  };
};

// 异步函数
export const main: TcbEventFunction<void, Promise<string>> = async function (
  event,
  context,
) {
  return new Promise((resolve) => {
    setImmediate(() => {
      resolve("done.");
    });
  });
};

// SSE
export const main: TcbEventFunction<void, Promise<string>> = async function (
  event,
  context,
) {
  const sse = context.sse?.();

  if (sse && !sse.closed) {
    sse.on("close", () => {
      console.log("sse closed");
    });

    sse.send({ data: "hello from sse function" });

    sse.send([
      { data: "This is the first message." },
      { data: "This is the second message." },
    ]);
  }
  return "";
};

// WebSocket
export const main: TcbEventFunction = async function (event, context) {
  if (context.ws) {
    context.ws.on("open", (msg) => {
      console.log("open: ", msg);
    });
    context.ws.on("error", (msg) => {
      console.log("error: ", msg);
    });
    context.ws.on("close", (msg) => {
      console.log("close: ", msg);
    });
    context.ws.on("message", (msg) => {
      console.log("message: ", msg);
    });
    context.ws.send("hello from websocket function");
  }
};
main.handleUpgrade = async function (context) {
  return {
    allowWebSocket: true,
  };
};

项目组织结构​

基于 TypeScript 的多函数项目​

.
├── README.md
├── Dockerfile
├── src/
│   ├── func-a/
│   │   ├── built/               # 编译后代码
│   │   ├── src/                 # TypeScript 源码
│   │   ├── package.json
│   │   ├── cloudbase-functions.json
│   │   └── tsconfig.json
│   └── func-b/
│       ├── built/
│       ├── src/
│       ├── package.json
│       └── tsconfig.json
├── package.json
└── tsconfig.json

项目结构参考：TypeScript 模板项目

单函数项目​

.
├── README.md
├── built/                       # 编译后代码
├── src/                         # TypeScript 源码
├── Dockerfile
├── package.json
├── cloudbase-functions.json
└── tsconfig.json

💡 提示：JavaScript 项目无需 src、built、tsconfig.json 等目录和文件。

相关文档​