编写普通云函数

基础代码示例

以下是一个简单的 Node.js 云函数示例，展示如何处理入参并返回结果：

// index.js - 云函数入口文件
exports.main = async (event, context) => {
	// 1. 解析云函数入参
	const { a, b } = event;

	// 2. 执行业务逻辑
	const sum = a + b;

	// 3. 返回结果
	return {
		sum,
		timestamp: Date.now(),
		requestId: context.requestId,
	};
};

异步处理实践

由于实例的管理由平台自动处理，推荐云函数采用 async/await 模式，避免使用 Promise 链式调用：

exports.main = async (event, context) => {
	// ❌ 不推荐：Promise 链式调用
	getList().then((res) => {
		// do something...
	});

	// ✅ 推荐：使用 async/await
	const res = await getList();
	// do something...
};

函数入参详解

每个云函数调用都会收到两个重要对象：event 和 context。

event 对象

event 对象包含触发云函数的事件数据，其内容根据触发方式不同而变化：

小程序调用：包含小程序端传入的参数
HTTP 请求调用：包含 HTTP 请求信息（如请求头、请求体等）
定时触发：包含定时触发的相关信息

context 对象

context 对象提供调用上下文信息，帮助您了解函数的运行环境和调用方式：

请求 ID：当前调用的唯一标识符
调用来源：触发函数的服务或客户端信息
执行环境：函数的运行时信息
用户身份：调用方的身份信息（如有）

函数返回值

云函数支持两种响应方式：简单响应和集成响应。系统会根据返回值的格式自动识别响应类型。

简单响应

直接返回数据，系统自动生成标准的 HTTP 响应。

返回字符串
返回 JSON

exports.main = async () => {
  return "Hello CloudBase";
};

HTTP 响应：

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

Hello CloudBase

exports.main = async () => {
  return {
    success: true,
    data: { id: 123, name: "CloudBase" },
    timestamp: Date.now()
  };
};

HTTP 响应：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"success":true,"data":{"id":123,"name":"CloudBase"},"timestamp":1699999999999}

集成响应（高级）

当需要精确控制 HTTP 状态码、响应头等信息时，使用集成响应格式：

{
  statusCode: number,           // HTTP 状态码（必填）
  headers: {                    // HTTP 响应头（可选）
    "headerName": "headerValue"
  },
  body: string,                 // 响应体内容（可选）
  isBase64Encoded: boolean      // body 是否为 Base64 编码（可选）
}

💡 识别规则：返回值包含 statusCode 字段时，系统会识别为集成响应。

集成响应示例

返回 HTML 页面
页面重定向
返回图片
错误响应
返回 JavaScript

exports.main = async () => {
  return {
    statusCode: 200,
    headers: {
      "Content-Type": "text/html; charset=utf-8"
    },
    body: `
      <!DOCTYPE html>
      <html>
        <head><title>CloudBase</title></head>
        <body>
          <h1>欢迎使用云开发</h1>
          <p>这是通过云函数返回的 HTML 页面</p>
        </body>
      </html>
    `
  };
};

浏览器访问时会直接渲染该 HTML 页面。

exports.main = async (event) => {
  const { path } = event;
  
  return {
    statusCode: 302,
    headers: {
      "Location": `https://docs.cloudbase.net${path}`
    }
  };
};

访问云函数时会自动跳转到指定 URL。

const fs = require('fs');
const path = require('path');

exports.main = async () => {
  // 读取图片文件并转换为 Base64
  const imagePath = path.join(__dirname, 'image.png');
  const imageBuffer = fs.readFileSync(imagePath);
  const base64Image = imageBuffer.toString('base64');
  
  return {
    statusCode: 200,
    headers: {
      "Content-Type": "image/png"
    },
    body: base64Image,
    isBase64Encoded: true
  };
};

⚠️ 注意：二进制文件（图片、音视频等）必须设置 isBase64Encoded: true。

exports.main = async (event) => {
  const { queryStringParameters } = event;
  
  // 参数验证
  if (!queryStringParameters?.userId) {
    return {
      statusCode: 400,
      headers: {
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        error: "Bad Request",
        message: "userId 参数不能为空"
      })
    };
  }
  
  // 业务逻辑
  const userId = queryStringParameters.userId;
  
  try {
    // ... 处理业务逻辑
    return {
      statusCode: 200,
      body: JSON.stringify({ success: true })
    };
  } catch (error) {
    return {
      statusCode: 500,
      body: JSON.stringify({
        error: "Internal Server Error",
        message: error.message
      })
    };
  }
};

exports.main = async () => {
  return {
    statusCode: 200,
    headers: {
      "Content-Type": "application/javascript"
    },
    body: `
      console.log("Hello from CloudBase!");
      window.cloudbaseConfig = {
        envId: "your-env-id",
        region: "ap-shanghai"
      };
    `
  };
};

可用于动态生成 JavaScript 配置文件。

安装第三方依赖

当云函数需要使用第三方 npm 包时，需要先安装相应的依赖包。CloudBase 在线编辑器提供了便捷的依赖管理功能。

打开终端

在 CloudBase 在线编辑器中，您可以通过以下方式打开终端：

快捷键：使用 Ctrl + J（Windows/Linux） 或 command + J（macOS）
菜单操作：点击编辑器上方的「终端」按钮，选择「新建终端」

安装依赖

在终端中使用 npm add 命令安装所需的依赖包。

以安装 CloudBase Node.js SDK 为例：

npm add @cloudbase/node-sdk

安装其他常用依赖包：

# 时区处理库
npm add moment-timezone

# HTTP 请求库
npm add axios

# 工具库
npm add lodash

使用依赖

安装完成后，您可以在代码中引用这些依赖：

在云函数 Node.js 环境中无法直接采用 ES Module 规范编写代码，主要原因在于，云函数默认支持的入口文件（index.js）必须遵循 CommonJS 规范，若需要使用 ES Module 规范请参考使用-es-module-规范

const cloudbase = require('@cloudbase/node-sdk');

exports.main = async (event, context) => {
	// 初始化 CloudBase
	const app = cloudbase.init({
		env: 'your-envid', // 替换为您的环境 ID
	});

	const db = app.database();
	const collection = db.collection('users');

	// 查询数据
	const { data } = await collection.get();

	return {
		success: true,
		count: data.length,
	};
};

上传和部署

完成代码编写和依赖安装后，根据项目情况选择相应的上传方式：

有第三方依赖：点击「保存并安装依赖」按钮
- 系统会自动上传代码文件和 package.json
- 在云端环境中自动执行 npm install 安装依赖
- 确保云函数运行时能够正确加载所有依赖包
无第三方依赖：点击「保存」按钮
- 仅上传代码文件
- 适用于未使用第三方依赖的云函数

依赖管理提示

避免安装过多不必要的依赖，以减少函数包的大小和启动时间

环境变量使用

云函数可以通过 process.env 获取环境变量，这是管理配置信息的实践：

获取环境变量

exports.main = async (event, context) => {
	// 获取环境变量
	const dbUrl = process.env.DATABASE_URL;
	const apiKey = process.env.API_KEY;
	const nodeEnv = process.env.NODE_ENV || 'development';

	// 使用环境变量进行配置
	const config = {
		database: dbUrl,
		apiKey: apiKey,
		debug: nodeEnv === 'development',
	};

	return {
		message: '环境变量获取成功',
		environment: nodeEnv,
	};
};

环境变量实践

exports.main = async (event, context) => {
	// 检查必需的环境变量
	const requiredEnvVars = ['DATABASE_URL', 'API_KEY'];
	const missingVars = requiredEnvVars.filter((varName) => !process.env[varName]);

	if (missingVars.length > 0) {
		throw new Error(`缺少必需的环境变量: ${missingVars.join(', ')}`);
	}

	// 安全地使用环境变量
	const config = {
		dbUrl: process.env.DATABASE_URL,
		apiKey: process.env.API_KEY,
		timeout: parseInt(process.env.TIMEOUT) || 5000,
	};

	return { success: true, config };
};

注意

敏感信息（如 API 密钥、数据库连接字符串）应通过环境变量传递，不要硬编码在代码中
环境变量值始终是字符串类型，需要时请进行类型转换
建议为环境变量设置默认值，提高代码的健壮性

时区设置

云函数的运行环境内保持的是 UTC 时间，即 0 时区时间，和北京时间有 8 小时的时间差。

可以通过语言的时间处理相关库或代码包（如 moment-timezone），识别 UTC 时间并转换为+8 区北京时间。

时区处理示例

const moment = require('moment-timezone'); // 需在 package.json 中指定并安装依赖

exports.main = async (event, context) => {
	// javascript date
	console.log(new Date()); // 2021-03-16T08:04:07.441Z (UTC+0)
	console.log(moment().tz('Asia/Shanghai').format()); // 2021-03-16T16:04:07+08:00 (UTC+8)

	// 获取当前北京时间
	const beijingTime = moment().tz('Asia/Shanghai');

	return {
		utcTime: new Date().toISOString(),
		beijingTime: beijingTime.format(),
		timestamp: beijingTime.valueOf(),
	};
};

时区处理实践

const moment = require('moment-timezone');

exports.main = async (event, context) => {
	// 统一时区处理函数
	const getBeijingTime = (date = new Date()) => {
		return moment(date).tz('Asia/Shanghai');
	};

	// 格式化时间输出
	const formatTime = (date, format = 'YYYY-MM-DD HH:mm:ss') => {
		return getBeijingTime(date).format(format);
	};

	// 业务逻辑中使用
	const currentTime = getBeijingTime();
	const formattedTime = formatTime();

	console.log('当前北京时间:', formattedTime);

	return {
		success: true,
		currentTime: formattedTime,
		timestamp: currentTime.valueOf(),
	};
};

使用 ES Module 规范

在云函数 Node.js 环境中无法直接采用 ES Module 规范编写代码，主要原因在于，云函数默认支持的入口文件（index.js）必须遵循 CommonJS 规范，并且文件名必须为 「index.js」。然而，Node.js 对于符合 ES Module 规范的模块文件要求其扩展名为 .mjs。

在云函数中使用 ES Module 需要创建三个核心文件，形成完整的调用链路：index.js → entry.mjs → util.mjs

项目结构

cloud-function/

Sunbelt Computer Software

PL/B Language Development and Support

编写普通云函数

基础代码示例

异步处理实践

函数入参详解

event 对象

context 对象

函数返回值

简单响应

集成响应（高级）

集成响应示例

安装第三方依赖

打开终端

安装依赖

使用依赖

上传和部署

环境变量使用

获取环境变量

环境变量实践

时区设置

时区处理示例

时区处理实践

使用 ES Module 规范

项目结构

Sunbelt Computer Software

PL/B Language Development and Support

基础代码示例​

异步处理实践​

函数入参详解​

event 对象​

context 对象​

函数返回值​

简单响应​

集成响应（高级）​

集成响应示例​

安装第三方依赖​

打开终端​

安装依赖​

使用依赖​

上传和部署​

环境变量使用​

获取环境变量​

环境变量实践​

时区设置​

时区处理示例​

时区处理实践​

使用 ES Module 规范​

项目结构​

基础代码示例

异步处理实践

函数入参详解

event 对象

context 对象

函数返回值

简单响应

集成响应（高级）

集成响应示例

安装第三方依赖

打开终端

安装依赖

使用依赖

上传和部署

环境变量使用

获取环境变量

环境变量实践

时区设置

时区处理示例

时区处理实践

使用 ES Module 规范

项目结构