在自动化脚本中如何执行本地、离线自动化脚？

原创于 2026-07-18 08:00:05 发布 · 157 阅读

本内容遵循CC 4.0 BY-SA版权协议

自动化脚本的执行方式灵活多样，既支持从云端拉取在线脚本，也支持直接运行存放在手机本地的 JavaScript 文件。在实际开发与调试过程中，出于网络环境受限、脚本调试需要或隐私安全等考虑，开发者往往更倾向于执行本地、离线的自动化脚本。本文将基于冰狐智能辅助的官方 API，详细梳理在冰狐平台中执行本地、离线自动化脚本的两种核心方法，并探讨其适用场景与注意事项。

一、核心 API 概述

冰狐智能辅助提供了两个用于脚本调用的核心函数：setDefaultScript 与 callScript。这两个函数均支持本地脚本的执行，但在工作机制和使用场景上存在显著差异。理解两者的区别，是正确选用 API 的前提。

二、方法一：使用 `setDefaultScript` 设置默认脚本

setDefaultScript 函数的作用是设置一个“默认脚本”。一旦调用该函数进行设置，其效果是永久有效的，除非开发者重新调用该函数并传入新的脚本路径，或传入空字符串来取消默认脚本的设置。

2.1 函数原型与参数

该函数接受一个字符串参数，即脚本的路径。根据官方文档，路径支持以下几种形式：

APK 资源内的脚本：使用 asset: 前缀，例如 'asset:xx.js'。这种方式适用于将脚本随 APK 打包发布，供内置脚本调用。
相对路径脚本：直接传入文件名，例如 'xx.js'。相对路径的基准目录通常是应用的私有存储目录或脚本根目录。
在线脚本：直接传入脚本名（不带路径前缀），例如 'xx'。此时平台会尝试从冰狐服务器拉取该脚本。
绝对路径脚本：传入完整的文件系统路径，例如 '/sdcard/xx.js'。这是执行本地离线脚本最直接的方式。

2.2 适用场景

setDefaultScript 适用于需要全局替换当前自动化任务入口的场景。例如，在脚本开发过程中，开发者可能希望临时切换到另一个本地版本来调试特定功能，而不必修改每次调用的代码。设置默认脚本后，平台后续的自动化执行入口将自动指向该脚本，直到被重新设置或取消。

2.3 使用示例

function main() {
    // 设置绝对路径下的本地脚本为默认脚本
    setDefaultScript('/sdcard/my_script.js');
    // 此后，平台将默认执行 /sdcard/my_script.js
}

需要注意的是，该函数仅负责“设置”默认脚本，并不会立即执行该脚本。实际的执行时机取决于平台后续的自动化调度逻辑。

三、方法二：使用 `callScript` 直接调用脚本

与 setDefaultScript 的“设置”语义不同，callScript 函数的作用是立即调用指定的脚本。这是执行本地离线脚本更常用、更直接的方式。

3.1 函数原型与参数

callScript 的函数签名如下：

callScript(scriptName, params...)

scriptName（必填）：字符串类型，指定要调用的脚本名称。同样支持多种路径格式：
- APK 资源文件：'asset:temp.js'
- 本地 JS 文件：'/sdcard/temp.js'
- 在线脚本：直接传入脚本名，如 'test'
params...（选填）：可变参数，任意数量。这些参数会直接透传给被调用脚本的 main 函数。

3.2 同步执行与线程模型

官方文档明确指出，callScript 是同步调用，它会执行移动端脚本中的 main 函数，并返回该函数的返回值。这意味着调用 callScript 的线程会被阻塞，直到被调用的脚本执行完毕。

重要限制：由于 callScript 不会创建独立的线程，而是直接在当前线程中执行，因此不能在 UI 线程（主线程）中使用，否则可能导致界面卡顿甚至 ANR（Application Not Responding）。官方文档建议，在 UI 相关代码中应使用 runTask 来替代。

3.3 参数传递与返回值

callScript 支持将任意数量的参数传递给目标脚本。目标脚本的 main 函数需要按顺序接收这些参数：

调用端代码：

// 调用本地脚本，并传递两个参数
callScript('/sdcard/test.js', 12, 'abc');

被调用的本地脚本 test.js：

function main(id, name) {
    // id: 12, name: 'abc'
    console.log('id:' + id + ' name:' + name);
    return name + id;  // 返回值将作为 callScript 的返回值
}

如上所示，callScript 的返回值即为目标脚本 main 函数的返回值。这使得 callScript 不仅可以执行脚本，还可以实现脚本间的数据交换。

四、两种方法的对比与选型建议

维度	`setDefaultScript`	`callScript`
语义	设置默认脚本（全局生效）	立即执行指定脚本
执行时机	设置后由平台调度触发	调用时立即执行
线程模型	取决于平台调度	同步执行，阻塞当前线程
参数传递	不支持动态传参	支持任意数量参数透传
返回值	无直接返回值	返回目标脚本 `main` 函数的返回值
适用场景	全局替换自动化入口	按需调用特定脚本、脚本间协作

在实际开发中，如果只是临时执行某个本地脚本进行测试或功能调用，应优先选择 callScript，因为它更灵活、支持参数传递且能获取返回值。而 setDefaultScript 更适合需要持久化改变自动化任务入口的场景，例如在应用启动时根据配置动态决定加载哪个脚本作为主任务。

五、本地脚本路径的注意事项

在执行本地离线脚本时，路径的正确性至关重要。根据官方文档的说明，以下三种本地脚本路径是受支持的：

asset: 前缀：指向打包在 APK 中的资源文件。这种方式适合将核心脚本与 APP 一起分发，无需额外从外部加载。
绝对路径：如 /sdcard/xxx.js，指向手机存储中的具体文件。这是执行外部离线脚本最通用的方式。
相对路径：如 xxx.js，其基准目录通常为应用的私有存储目录或脚本工作目录，具体行为可能取决于平台实现。

对于存放在手机外部存储（如 /sdcard/）的脚本，需要确保应用已获取相应的存储读取权限，否则文件访问可能失败。

六、总结

冰狐智能辅助平台通过 setDefaultScript 和 callScript 两个核心 API，为开发者提供了灵活且完备的本地、离线脚本执行能力。setDefaultScript 适用于全局默认脚本的设置，而 callScript 则更适合按需调用、参数传递和脚本间协作的场景。理解两者的工作机制、线程模型和适用边界，有助于开发者在编写自动化脚本时做出正确的技术选型，从而构建更稳定、高效的自动化解决方案。

在实际项目中，建议优先使用 callScript 配合绝对路径来执行本地离线脚本，并注意避免在 UI 线程中调用，以防止界面阻塞。同时，合理利用参数传递和返回值机制，可以实现脚本模块化，提升代码的复用性和可维护性。

标签