跳到主要内容

编写 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框架。

函数路由​

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 等目录和文件。

相关文档​