文档中心

云手机

请输入

最佳实践

Script 脚本内容规范

本文介绍 Script 字段的内容格式、编写规则和使用限制，帮助您正确编写自动化操作脚本。

脚本格式

Script 字段用于传入需要在云手机实例中依次执行的操作。编写脚本时，请遵循以下规则：

每行仅编写一个动作，动作按照从上到下的顺序执行。

动作采用函数调用格式：action_name(arg1, arg2, key=value)，例如 tap(500, 800)、wait(2)、take_screenshot()。

空行和以 # 开头的整行注释不会作为有效动作，不计入有效动作行数。

不建议在动作后添加行尾注释。不同动作可能采用不同的处理方式，容易导致脚本执行结果不符合预期。

Script 仅接收脚本文本。请勿在脚本中添加 Markdown 代码块标记、JSON 对象、JSON 数组或自然语言说明。

注意

单个脚本的内容大小不能超过 100000 bytes，约为 100 KB。单个 ScriptRun 最多包含 500 行有效动作。使用 ChainRun 时，其中所有 ScriptRun 节点的有效动作行数合计不能超过 500 行。

坐标规范

tap()、click() 等动作中的坐标表示当前操作画布上的像素位置：

坐标原点 (0, 0) 位于画布左上角。

x 轴向右递增。

y 轴向下递增。

注意

建议在请求中同时设置 Resolution，并按照对应分辨率编写坐标。未设置 Resolution 时，不同云手机实例可能采用不同的默认分辨率，导致固定坐标对应的实际点击位置发生偏移。

例如，以下动作表示点击画布中横坐标为 500、纵坐标为 800 的位置：

注意

请确保脚本中的坐标未超出 Resolution 指定的画布范围。复用固定坐标脚本时，应保持目标云手机实例的分辨率一致。

注释规范

您可以使用以 # 开头的整行注释说明操作目的。整行注释和空行不会计入 500 行有效动作限制。

示例：

请勿依赖行尾注释。例如，不建议采用以下写法：

建议改为：

Script 传入方式

您可以通过请求体中的 Script 字段或上传脚本文件的方式传入脚本。一个请求中必须且只能使用其中一种方式。

注意

Script 和 File 不能同时传入。如果同时传入，或者两者均未传入，请求将无法正常处理。

通过 Script 字段传入

在 JSON 请求中，Script 的值必须为字符串，脚本中的换行符使用 \n 表示。

示例：

请勿将 JSON 对象或数组作为 Script 的值。以下写法不正确：

正确写法如下：

通过 File 字段上传

上传脚本文件时，请使用 multipart/form-data 请求，并通过 File 字段上传文件。系统将读取文件中的文本内容作为脚本。

常用动作

动作	示例	说明
点击坐标	tap(500, 800) 或 click(500, 800)	点击当前画布中的指定坐标。
等待	wait(2)	等待指定秒数。可用于等待页面加载、弹窗显示或动画完成。
截图	take_screenshot()	保存当前画面，可用于后续节点处理或问题排查。

完整示例

以下脚本依次执行点击、等待和截图操作：

在 JSON 请求中传入时，需要将脚本写为字符串：

常见问题

Script 中是否可以包含 Markdown 代码块标记？

不可以。Script 仅接收脚本文本，请勿添加三个反引号等 Markdown 格式标记。

错误示例：

正确示例：

是否可以同时传入 Script 和 File？

不可以。一个请求中必须且只能传入 Script 或 File。

为什么相同坐标在不同云手机实例中的点击位置不同？

不同云手机实例可能采用不同的画布分辨率。建议在请求中设置 Resolution，并按照该分辨率编写和复用坐标。

空行和注释是否计入有效动作行数？

空行和以 # 开头的整行注释不计入有效动作行数。包含动作的行会计入有效动作行数。

最近更新时间：2026.10.26 20:09:08

这个页面对您有帮助吗？

有用

无用