在写自动化脚本时如何高效使用各种日志功能？

在开发自动化脚本时日志是脚本调试、运行监控、异常排查的核心工具。平台提供了在线日志、离线日志、悬浮日志三种差异化的日志能力，分别适配实时调试、离线追溯、本地可视化监控的场景需求。本文将从三种日志的核心特性、API 使用方法、场景化实践、组合使用技巧等方面，结合完整 Demo 源码，讲解如何高效利用冰狐原生 JS API 实现日志的精细化管理，让脚本开发与运维更高效。

一、冰狐日志体系核心特性

冰狐智能辅助的日志体系基于平台自研的 ECMAScript 子集构建，所有日志 API 均为平台原生提供，无需引入外部依赖，且支持在线编辑、动态部署后立即生效。三种日志能力各有侧重，可单独使用也可组合搭配：

• 在线日志：实时性强，支持多级别日志输出，可在网页端设备管理界面实时查看，适配脚本开发阶段的实时调试；
• 离线日志：将日志持久化到设备本地文件，支持日志留存与离线追溯，解决线上脚本运行异常无法实时监控的问题；
• 悬浮日志：在设备屏幕生成悬浮日志框，本地可视化展示运行信息，适配脚本本地测试时的直观监控需求。

三种日志均支持与冰狐的系统事件回调、多线程编程、全局变量等特性结合，实现日志的精准触发与多维度监控。

二、在线日志

在线日志是冰狐最基础也是使用最频繁的日志功能，通过console对象实现多级别日志输出，配合setLogLevel可实现日志级别的灵活控制，所有日志可在冰狐网页端「移动端」/「我的设备」中点击对应设备的「LOG」按钮实时查看。

1. 核心 API 与日志级别

冰狐在线日志提供 4 个核心输出 API，对应不同的日志级别，同时提供日志级别控制 API，实现日志的精细化过滤：

级别规则：设置某一级别后，将显示该级别及更高优先级的日志，如设置级别为 2（warn），则仅显示warn和error日志，过滤debug和info日志，有效减少日志冗余。

2. 在线日志使用规范

3. 在线日志 Demo 源码

// 在线日志核心使用Demo
function main() {
// 1. 设置日志级别为4，开发阶段显示所有日志
setLogLevel(4);
console.info(`当前日志级别：${getLogLevel()}`);

// 2. 记录脚本启动信息
console.log('自动化脚本开始执行，当前设备UUID：' + rsUUID);
console.log(`当前运行APP：${getCurAppName()}，包名：${getCurPackageName()}`);

// 3. 尝试启动x信，结合条件判断输出不同级别日志
var ret = launchApp('com.tencent.mm', 'txt*:x信', {maxStep: 40, afterWait: 2000});
if (1 == ret) {
console.log('x信启动成功，开始执行滚动操作');
// 循环执行滚动，记录循环次数
for (var i = 0; i < 3; i++) {
scroll('up', {distance: Math.random() * 0.5 + 0.45, duration: parseInt(Math.random() * 200 + 300)});
console.log(`第${i+1}次滚动完成`);
sleep(1000);
}
} else if (0 == ret) {
console.warn('x信未安装，无法执行后续操作');
} else {
console.error(`x信启动失败，返回码：${ret}，请检查无障碍权限或APP状态`);
}

// 4. 脚本执行结束记录
console.info('自动化脚本执行完毕');
}

三、离线日志

在线日志仅支持实时查看，无法留存历史日志，当脚本在无网络环境运行或线上运行出现偶发性异常时，离线日志成为关键的排查工具。冰狐通过setOfflineLogFileAPI 实现日志的本地文件持久化，设置后console对象的所有日志会同时写入本地文件，支持日志的离线查看与长期留存。

1. 核心 API 与参数说明

离线日志的核心是setOfflineLogFile，需在脚本开头调用，设置日志文件的存储路径与留存规则，其参数说明如下：

setOfflineLogFile(filename, enableOnlineLog, saveDays);

• filename（必填，字符串）：离线日志文件名，可带目录，如/sdcard/aznfz/wechat_auto.log；
• enableOnlineLog（选填，布尔）：是否开启在线日志，默认true，实现「在线 + 离线」双日志；
• saveDays（选填，整数）：日志留存天数，默认0（每次启动脚本重新创建日志）。

关键特性：

2. 离线日志使用注意事项

3. 离线日志 Demo 源码

// 离线日志核心使用Demo，结合在线日志实现双日志方案
function main() {
// 1. 设置离线日志文件，留存7天，开启在线日志
var logFileName = `/sdcard/aznfz/wechat_auto_${rsUUID}.log`;
setOfflineLogFile(logFileName, true, 7);
console.info(`离线日志已开启，文件路径：${logFileName}，留存7天`);

// 2. 设置日志级别，上线后改为2
setLogLevel(4);

// 3. 后续日志会同时输出到在线LOG和本地文件
console.log('脚本启动，开始执行x信自动化操作');
var isAccess = isAccessibilityEnabled();
if (!isAccess) {
console.error('无障碍功能未开启，脚本无法执行');
openAccessibilitySetting();
return;
}
console.log('无障碍功能已开启，开始启动x信');

var ret = launchApp('com.tencent.mm', 'txt*:x信', {maxStep: 40, afterWait: 2000});
if (1 == ret) {
console.log('x信启动成功，脚本执行完成');
} else {
console.error(`x信启动失败，返回码：${ret}`);
}

// 4. 脚本结束日志
console.info(`脚本执行完毕，所有日志已保存至${logFileName}`);
}

四、悬浮日志

悬浮日志通过Float对象在设备屏幕生成悬浮日志框，将运行信息本地可视化展示，无需打开网页端即可直观监控脚本运行状态，适配脚本本地测试、现场调试的场景需求，支持日志框样式自定义、显示 / 隐藏、清空等操作。

1. 核心 API 与配置规则

悬浮日志的核心 API 分为配置、输出、控制三类，所有配置必须在 main 函数第一行调用，确保悬浮框正常初始化：

（1）配置 API：Float.config(config)

用于自定义悬浮日志框的样式、位置、时间戳等，config为必选对象，包含以下子配置：

• itemStyle：日志文本样式，color（颜色，如#FFFFFF）、size（字号，整数）；
• floatStyle：悬浮框样式，width/height（宽高，整数）、gravity（对齐方式，如left|bottom）、backgroundColor（背景色）；
• addTime：是否添加时间戳，布尔值；
• touchable：是否可触摸，布尔值，默认false。

（2）输出 API：Float.message(msg)

用于向悬浮框输出日志信息，msg为必填字符串，支持模板字符串。

（3）控制 API

• Float.enable(enable)：开启 / 关闭悬浮框，布尔值，默认开启；
• Float.visible(visible)：显示 / 隐藏悬浮框，隐藏后再次显示会保留历史日志；
• Float.clear()：清空悬浮框所有日志信息。

2. 悬浮日志使用技巧

3. 悬浮日志 Demo 源码

// 悬浮日志核心使用Demo，结合x信自动化实现本地可视化监控
function main() {
// 1. 第一行配置悬浮日志，必选操作
Float.config({
itemStyle: {color: '#FFFFFF', size: 14}, // 白色14号字
floatStyle: {
width: 300,
height: 400,
gravity: 'left|bottom', // 左下对齐
backgroundColor: '#000000' // 黑色背景
},
addTime: true, // 显示时间戳
touchable: false // 不可触摸，防止误操作
});
Float.message('悬浮日志已开启，脚本开始执行');

// 2. 检查无障碍权限，悬浮日志输出
var isAccess = isAccessibilityEnabled();
if (!isAccess) {
Float.message('【错误】无障碍功能未开启，正在打开设置');
console.error('无障碍功能未开启');
openAccessibilitySetting();
toast('请开启无障碍权限后重新运行脚本', 3000);
return;
}
Float.message('【成功】无障碍功能已开启');

// 3. 启动x信，悬浮日志实时输出状态
Float.message('开始启动x信，包名：com.tencent.mm');
var ret = launchApp('com.tencent.mm', 'txt*:x信', {maxStep: 40, afterWait: 2000});
if (1 == ret) {
Float.message('【成功】x信启动完成，开始执行滚动操作');
console.log('x信启动成功');
// 循环滚动，悬浮日志记录次数
for (var i = 0; i < 3; i++) {
scroll('up', {distance: Math.random() * 0.5 + 0.45, duration: parseInt(Math.random() * 200 + 300)});
Float.message(`第${i+1}次滚动完成`);
console.log(`第${i+1}次滚动完成`);
sleep(1000);
}
// 清空悬浮日志，输出最终结果
Float.clear();
Float.message('【完成】x信自动化操作执行完毕，共滚动3次');
} else {
Float.message(`【错误】x信启动失败，返回码：${ret}`);
console.error(`x信启动失败，返回码：${ret}`);
toast(`x信启动失败，返回码：${ret}`, 3000);
}

// 4. 脚本执行完毕
console.info('脚本执行完毕');
}

五、三种日志的组合使用策略

冰狐的三种日志并非孤立存在，在实际开发中，根据开发阶段、运行环境、使用场景的不同，组合使用三种日志能实现最佳的监控与调试效果，以下是三种核心组合策略：

1. 开发调试阶段：在线日志 + 悬浮日志

适用场景：本地开发、脚本调试、功能验证；组合方式：开启setLogLevel(4)显示所有在线日志，配置悬浮日志实现本地可视化监控，无需频繁切换网页端即可查看运行状态；优势：实时性强、可视化直观，能快速定位开发过程中的语法错误、流程错误、API 调用错误。

2. 线上测试阶段：在线日志 + 离线日志

适用场景：远程设备测试、线上小范围验证；组合方式：设置setLogLevel(3)显示 debug 及以上级别日志，开启离线日志并设置留存 7 天，实现「实时监控 + 离线追溯」；优势：既可以在网页端实时查看测试状态，又能将日志持久化，便于测试完成后复盘问题，尤其适配偶发性异常的排查。

3. 正式运行阶段：离线日志 + 极简在线日志

适用场景：脚本正式上线、长期自动化运行；组合方式：设置setLogLevel(2)仅显示 warn 和 error 级别日志，开启离线日志并设置留存 15 天，关闭悬浮日志；优势：减少日志输出对脚本运行效率的影响，同时通过离线日志留存关键异常信息，当脚本运行异常时，可通过本地日志文件追溯原因。

4. 特殊场景：无网络运行

适用场景：设备无网络、离线环境运行脚本；组合方式：关闭在线日志（setOfflineLogFile的enableOnlineLog设为false），开启离线日志，配置悬浮日志；优势：通过悬浮日志实现本地可视化监控，通过离线日志实现运行信息持久化，解决无网络环境下的日志监控与追溯问题。

六、日志使用的最佳实践

七、总结

在线日志、离线日志、悬浮日志三大功能，覆盖了自动化脚本开发、测试、上线全生命周期的日志监控与追溯需求。在实际开发中，应根据脚本的运行环境、使用场景选择合适的日志方案，同时遵循日志分级、结构化、极简化的原则，在实现高效监控的同时，避免日志对脚本运行效率的影响。结合冰狐的系统事件回调、多线程编程、全局变量等特性，可实现日志的精准触发与多维度监控，让自动化脚本的开发与运维更高效、更可控。