跳到主要内容

编写 HTTP 云函数

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

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

安全警告

云函数和云托管服务运行时能够通过 HTTP header 和环境变量获取开发凭证，请谨慎处理这些敏感信息（包含但不仅限于HTTP header: x-cloudbase-context, 环境变量: TENCENTCLOUD_SECRETID/TENCENTCLOUD_SECRETKEY 等），避免直接将原始请求头和环境变量直接暴露给用户。使用类似 httpbin 这种会自动将请求头直接返回给用户的服务时，请务必处理该特性，否则会存在较大安全风险。

快速开始​

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

创建 index.js 作为 HTTP 函数入口文件。HTTP 云函数本质是一个标准 Web 服务，需在 9000 端口 上监听 HTTP 请求：

const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
  res.end('Hello World!');
});

// HTTP 云函数默认端口必须为 9000
server.listen(9000, '0.0.0.0', () => {
  console.log('Server running at http://localhost:9000/');
});

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

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

#!/bin/bash
node index.js

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

项目结构​

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

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

使用 Web 框架开发​

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

多路由也由 Web 框架实现，例如通过 Express 的 app.get() / app.post() 或 Flask 的 @app.route() 定义不同路径的处理逻辑。

调用云开发资源（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 云函数提供两种实时通信方式：「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

相关文档​