编写普通云函数

基础代码示例

以下是一个简单的 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/
├── index.js        # 云函数入口文件（CommonJS）
├── entry.mjs       # ES Module 入口文件
└── src
	└── util.mjs       # 业务逻辑模块，命名可自定义

1. 创建云函数入口文件 index.js

// index.js - 云函数入口文件
exports.main = async (event, context) => {
	try {
		// 动态导入 ES Module 入口文件
		const { entry } = await import('./entry.mjs');
		return await entry(event, context);
	} catch (error) {
		console.error('云函数执行失败:', error);
		return {
			success: false,
			error: error.message,
			requestId: context.request_id
		};
	}
};

2. 创建 ES Module 入口文件 entry.mjs

// entry.mjs - ES Module 入口文件
import { getUserList } from './src/util.mjs';

/**
 * ES Module 入口函数
 * @param {Object} event - 事件对象
 * @param {Object} context - 上下文对象
 * @returns {Promise<Object>} 处理结果
 */
export const entry = async (event, context) => {
	return getUserList(event, context);
};

3. 创建业务逻辑模块 util.mjs

// src/util.mjs - 业务逻辑模块
import cloudbase from '@cloudbase/node-sdk';

const app = cloudbase.init({
    env: 'your-envid', // 替换为您的环境 ID
});

const models = app.models;

export const getUserList = async (event) => {
	const res = await models.user.list({});

	return {
		success: true,
		data: res,
	};
};

💡 注意: ES Module 文件必须使用 .mjs 扩展名，这样 Node.js 才能正确识别并处理 ES Module 语法。

错误处理与日志记录

错误处理实践

exports.main = async (event, context) => {
	try {
		// 参数验证
		if (!event.userId) {
			throw new Error('缺少必需参数: userId');
		}

		// 业务逻辑处理
		const result = await processUserData(event.userId);

		return {
			success: true,
			data: result,
		};
	} catch (error) {
		// 记录错误日志
		console.error('函数执行失败:', {
			error: error.message,
			stack: error.stack,
			event,
			requestId: context.requestId,
		});

		// 返回友好的错误信息
		return {
			success: false,
			error: error.message,
			requestId: context.requestId,
		};
	}
};

性能优化建议

执行时间优化

exports.main = async (event, context) => {
	const startTime = Date.now();

	try {
		// 使用并行处理提升性能
		const promises = event.items.map((item) => processItem(item));
		const results = await Promise.all(promises);

		const duration = Date.now() - startTime;
		console.log(`函数执行耗时: ${duration}ms`);

		return {
			success: true,
			data: results,
			duration,
		};
	} catch (error) {
		console.error('执行错误:', error);
		throw error;
	}
};

内存使用优化

exports.main = async (event, context) => {
	// 分批处理大数据，避免内存溢出
	const batchSize = parseInt(process.env.BATCH_SIZE) || 100;
	const results = [];

	for (let i = 0; i < event.data.length; i += batchSize) {
		const batch = event.data.slice(i, i + batchSize);
		const batchResult = await processBatch(batch);
		results.push(...batchResult);

		// 及时清理不需要的变量
		batch.length = 0;

		// 记录处理进度
		console.log(`已处理 ${Math.min(i + batchSize, event.data.length)}/${event.data.length} 条数据`);
	}

	return results;
};

基础代码示例​

异步处理实践​

函数入参详解​

event 对象​

context 对象​

函数返回值​

简单响应​

集成响应（高级）​

集成响应示例​

安装第三方依赖​

打开终端​

安装依赖​

使用依赖​

上传和部署​

环境变量使用​

获取环境变量​

环境变量实践​

时区设置​

时区处理示例​

时区处理实践​

使用 ES Module 规范​

项目结构​

1. 创建云函数入口文件 index.js​

2. 创建 ES Module 入口文件 entry.mjs​

3. 创建业务逻辑模块 util.mjs​

错误处理与日志记录​

错误处理实践​

性能优化建议​

执行时间优化​

内存使用优化​