使用指南

云函数允许你使用 JavaScript 在服务端处理游戏逻辑、读写云变量和数据表，以及响应
多人联机房间事件。代码在服务端运行，不需要由玩家设备执行。

云函数类型

ShangCloud 提供两种云函数：

类型	适用场景	特点
主节点函数	数据查询、变量计算、调用外部接口、处理事件系统动作	内置接口同步返回结果，可以将计算结果返回给调用方
边缘节点函数	房间消息拦截、成员进出、房间广播、实时互动	在多人联机房间中执行，应尽快完成；大部分写操作只负责提交，不返回最终处理结果

需要查询数据并根据结果继续处理时，请使用主节点函数；需要处理实时房间事件时，请使用
边缘节点函数。

创建云函数

进入开发者中心，选择目标应用并打开“云函数”页面，然后创建函数。

创建时需要填写：

函数名称：只能包含英文字母、数字和下划线，不能以数字开头；

运行节点：选择主节点或边缘节点；

触发器：决定函数在什么时候运行；

入口函数：通常使用 main；

代码：服务端 JavaScript 源码；

启用状态：关闭后不会接受新的调用。

主节点函数保存后可以在页面中试运行。边缘节点函数需要通过多人联机房间事件触发，运行
结果和 console 输出可在“运行日志”中查看。

基本结构

入口函数接收 ctx 和 payload 两个参数：

`ctx` 调用上下文

常用字段如下：

字段	说明
`ctx.app`	当前应用
`ctx.fn`	当前函数名称
`ctx.trigger`	本次调用的触发器
`ctx.uid`	当前玩家 UID；没有关联玩家时可能为空
`ctx.nickname`	当前玩家昵称，仅部分房间触发器提供
`ctx.room`	当前房间，仅边缘节点房间触发器提供
`ctx.now`	本次调用的时间戳

使用玩家私有数据前，建议先检查 ctx.uid：

`payload` 调用参数

payload 是字符串。如果调用方传入 JSON，需要在函数中自行解析：

如果参数不一定是合法 JSON，可以使用 try/catch：

返回值

可以返回字符串、数字、布尔值、数组或对象：

主节点函数的返回值会返回给调用方。边缘节点函数的返回值是否生效，取决于所使用的
触发器。

控制台日志

云函数支持以下日志方法：

日志可在云函数页面的“运行日志”中查看。建议记录必要的标识和处理结果，不要在日志中
输出访问令牌、密码或其他敏感信息。

主节点函数

主节点函数适合需要读取结果、执行数据计算或调用外部接口的场景。

云变量

云变量分为应用级变量和玩家私有变量，两者是相互独立的。

类型	读取	写入	删除
应用级变量	`kv.get(key)`	`kv.set(key, value)`	`kv.delete(key)`
玩家私有变量	`kv.getUser(uid, key)`	`kv.setUser(uid, key, value)`	`kv.deleteUser(uid, key)`

应用级变量

应用级变量由当前应用的所有玩家共享，适合保存公告、公共配置或全局状态：

玩家私有变量

玩家私有变量按 UID 隔离，适合保存等级、金币、背包和个人进度：

请特别注意：

即使 ctx.uid 存在，kv.get() 也不会自动读取当前玩家的数据。

数值变量

云变量值按字符串使用。参与计算前应显式转换，写回时再转换为字符串：

应用数据表

主节点函数可以查询和修改当前应用的数据表：

查询示例：

写入示例：

使用前请先在开发者中心创建对应的数据表和字段。字段名称、数据类型以及数据访问规则
必须与表配置一致。

HTTP 请求

主节点函数可以向允许访问的外部地址发送 HTTP 请求：

示例：

外部地址可能受到安全策略限制。请求失败时会抛出异常，可以使用 try/catch 处理：

通过事件系统调用主节点函数

事件系统可以把“变量变化”等事件交给主节点云函数处理。

配置步骤：

在事件系统中创建事件模板；

创建“触发云函数”动作并选择目标主节点函数；

如需将事件字段传给函数，开启“合并当前上下文”；

创建规则并关联该动作。

变量变化事件参数

假设玩家私有变量 level 从 80 更新为 90，开启“合并当前上下文”后，函数收到的
payload 类似：

{
  "level": "90",
  "variable_name": "level",
  "old_value": "80",
  "new_value": "90",
  "delta": 10.0,
  "write_source": "external"
}

字段说明：

字段	说明
`variable_name`	发生变化的变量名
`old_value`	写入前的值
`new_value`	写入后的值
`delta`	数值变化量；非数值变量可能为空
`write_source`	本次写入的来源

这些字段是本次事件的上下文，不是持久化云变量，应从 payload 中读取：

如果需要重新读取触发事件的玩家当前数据，应使用玩家私有变量接口：

如果没有开启“合并当前上下文”，payload 只包含动作中手动填写的参数。

示例：等级提升后发放金币

边缘节点函数

边缘节点函数用于处理多人联机房间中的实时事件。

触发器

触发器	说明
`room_create`	房间创建
`room_destroy`	房间销毁
`room_join`	玩家加入房间
`room_leave`	玩家离开房间
`message`	收到房间消息，广播前触发
`call`	客户端主动调用房间函数
`tick`	按设置的间隔定时触发

房间接口

成员加入时发送通知：

消息拦截

message 触发器会在消息广播前执行。返回值具有以下含义：

返回值	效果
`false`	拦截消息，不再广播
字符串	使用返回的字符串替换原消息
其他值	放行原消息

示例：

边缘节点的数据写入

边缘节点函数可以提交应用级变量、玩家私有变量和数据表写入：

这些操作主要用于提交写入请求，不应依赖其返回值继续执行查询或计算。需要先读取数据再
决定如何处理时，应调用主节点函数。

边缘节点函数应保持简短，避免复杂循环、大量日志或耗时操作，以免影响房间消息处理。

在作品中调用

Scratch 扩展提供两类调用积木：

调用云函数：调用主节点函数，适合业务计算并等待返回结果；

调用房间云函数：调用当前多人联机房间中的边缘节点函数，需要先加入房间。

传入对象时，请先将参数转换成 JSON 字符串，例如：

{"score": 100, "mode": "ranked"}

函数返回对象时，调用方通常会收到 JSON 字符串，可根据作品端能力继续解析。

错误处理建议

检查玩家 UID

检查 JSON 参数

检查数值

处理内置接口异常

常见问题

`kv.get("level")` 为什么是空的？

kv.get() 读取应用级变量。如果 level 是玩家私有变量，应使用：

事件参数中有 `level`，为什么云变量读取不到？

事件参数和持久化云变量是两个不同概念：

为什么事件函数的 `payload` 没有 `new_value`？

请检查“触发云函数”动作是否开启了“合并当前上下文”。未开启时，函数只会收到动作中
手动配置的参数。

为什么测试时读不到线上玩家数据？

开发者中心的部分测试功能会使用隔离的测试玩家数据，避免调试操作影响真实玩家。请在
实际玩家调用或真实事件触发后查看对应结果。

为什么边缘节点写入后不能立即读取结果？

边缘节点函数面向实时房间事件，数据写入主要用于提交操作。需要读取写入结果或执行连续
的数据处理时，请改用主节点函数。

如何排查函数没有执行？

依次检查：

函数是否已保存并启用；

函数类型和触发器是否正确；

事件模板、规则和动作是否启用；

事件动作是否选择了正确的函数；

参数是否为有效 JSON；

“运行日志”中是否记录了异常；

玩家私有变量是否使用了 kv.getUser()，并且 ctx.uid 有值。

最佳实践

主节点函数负责数据查询、业务计算和需要结果的操作；

边缘节点函数负责简短的实时房间逻辑；

应用公共数据使用 kv.get()，玩家数据使用 kv.getUser()；

对所有外部参数进行类型和范围检查；

对 JSON 解析、数据表操作和 HTTP 请求进行异常处理；

不在日志或返回值中暴露访问令牌、密码等敏感数据；

避免在边缘节点函数中执行复杂循环或产生大量日志；

对金币、结算分数等重要变量，配合内容守护限制客户端直接写入；

保存函数后先使用测试功能验证，再接入正式事件或作品流程。

云函数类型#

创建云函数#

基本结构#

ctx 调用上下文#

payload 调用参数#

返回值#

控制台日志#

主节点函数#

云变量#

应用级变量#

玩家私有变量#

数值变量#

应用数据表#

HTTP 请求#

通过事件系统调用主节点函数#

变量变化事件参数#

示例：等级提升后发放金币#

边缘节点函数#

触发器#

房间接口#

消息拦截#

边缘节点的数据写入#

在作品中调用#

错误处理建议#

检查玩家 UID#

检查 JSON 参数#

检查数值#

处理内置接口异常#

常见问题#

kv.get("level") 为什么是空的？#

事件参数中有 level，为什么云变量读取不到？#

为什么事件函数的 payload 没有 new_value？#

为什么测试时读不到线上玩家数据？#

为什么边缘节点写入后不能立即读取结果？#

如何排查函数没有执行？#

最佳实践#