在自动化脚本中使用本地数据库

在移动端自动化脚本开发过程中，数据持久化是无法绕开的核心需求。无论是记录脚本运行日志、存储采集到的业务数据、保存用户配置参数，还是缓存临时交互信息，可靠的本地数据存储方案都能大幅提升自动化脚本的实用性与稳定性。自动化脚本内置了轻量化本地数据库模块，无需额外配置第三方数据库、无需设备 Root 权限，依托原生封装的 Database 系列 API，即可在移动端脚本中便捷实现数据表创建、数据增删改查、事务管理等完整数据库操作，完美适配离线脚本、本地自动化任务的数据存储场景。本文从基础认知、核心 API 解析、完整实操案例、事务应用、常见问题排查等维度，全面讲解冰狐自动化脚本中本地数据库的使用方法，帮助开发者快速掌握本地数据库的落地应用。

一、冰狐本地数据库基础认知

冰狐智能辅助平台区分移动端数据库 与服务端数据库，我们日常编写安卓端自动化脚本、离线脚本时使用的均为移动端本地数据库，该数据库基于轻量级嵌入式数据库封装，适配安卓全系列主流版本，具备占用资源少、响应速度快、离线可用的特点，完全脱离云端服务器运行，数据仅保存在当前设备本地，兼顾安全性与独立性。

从应用场景来看，本地数据库尤其适合三类自动化脚本：第一类是纯离线运行的自动化脚本，这类脚本打包为离线 APK 后不连接云端，所有数据读写都依赖本地存储；第二类是数据采集类脚本，比如 APP 内容抓取、表单信息统计等，需要批量缓存采集结果；第三类是长周期运行的自动化任务，如定时巡检、循环操作脚本，需要记录运行状态、异常信息、执行次数等日志数据，方便后续追溯与问题排查。相较于平台简易的键值对本地存储，数据库支持复杂数据表结构、多字段分类存储、条件查询与批量数据管理，在大数据量、结构化数据场景下优势更为明显。

在开始编码前，开发者无需额外安装数据库软件、配置驱动或权限，冰狐脚本引擎已将数据库能力内置，仅需在 JS 脚本中直接调用官方提供的 Database 对象及配套方法即可完成所有操作，开发流程简洁高效。

二、数据库核心 API 详细解析

结合冰狐官方数据库文档，平台移动端数据库共提供 8 个核心方法，涵盖数据库实例创建、表判断、SQL 执行、数据查询、事务控制、数据库关闭与删除全流程，所有方法均基于 JavaScript 语法编写，兼容平台标准脚本规范。下面逐一拆解每个 API 的作用、参数、返回值及基础用法，这是编写数据库脚本的基础。

（一）Database 构造函数

该函数用于创建并打开指定名称的本地数据库实例，是所有数据库操作的入口方法。

语法格式：var db = new Database(dbName);
参数说明：仅接收一个必填字符串类型参数dbName，即自定义数据库名称，同一设备中不同数据库名称相互独立，建议根据业务场景命名，如task_log、data_collect等。
使用要点：执行该代码后，若设备本地不存在对应名称的数据库，系统会自动创建数据库并打开；若数据库已存在，则直接打开连接。一个脚本中可创建多个不同名称的数据库实例，分别存储不同业务数据。

（二）isTableExist 方法

用于判断数据库内指定数据表是否存在，避免重复创建数据表引发报错，是脚本初始化阶段的常用方法。

语法格式：db.isTableExist(tableName);
参数说明：必填字符串类型参数tableName，代表需要检测的数据表名称。
返回值：布尔类型，数据表存在返回true，不存在返回false。
应用场景：通常搭配建表 SQL 使用，先判断表状态，不存在则执行建表语句，保证脚本重复运行时不会出错。

（三）exeSql 方法

核心通用方法，用于执行各类 DDL（数据定义）与 DML（数据操作）SQL 语句，包括建表、新增数据、修改数据、删除数据等非查询类操作。

语法格式：db.exeSql(sql);
参数说明：必填字符串类型参数sql，即标准 SQL 语句，语法遵循嵌入式数据库通用规则。
返回值：布尔类型，SQL 语句执行成功返回true，执行失败（语法错误、字段不匹配等）返回false，可通过返回值判断操作结果。
支持语句类型：CREATE TABLE（建表）、INSERT（插入数据）、UPDATE（更新数据）、DELETE（删除数据）等。

（四）query 方法

专属数据查询方法，用于执行 SELECT 查询语句，获取数据表中的结构化数据。

语法格式：db.query(sql);
参数说明：必填字符串类型参数sql，即 SELECT 查询 SQL 语句。
返回值：JSON 数组格式，数组中的每一个元素都是 JSON 对象，对应数据表中的一条数据记录；若无查询结果，返回空数组，便于脚本遍历解析数据。

（五）close 方法

用于关闭当前数据库连接。数据库连接属于系统资源，脚本完成所有数据库操作后必须主动调用该方法释放资源，长时间不关闭连接可能造成内存占用过高、脚本运行卡顿等问题。

语法格式：db.close();
参数：无参数，直接调用即可。
使用规范：建议将close()方法放在脚本数据库逻辑的末尾，即使脚本中途出现分支逻辑，也要保证所有执行路径最终都会关闭连接。

（六）delete 方法

用于彻底删除整个本地数据库，清空该数据库下所有数据表与数据，属于高风险操作，需谨慎使用。

语法格式：db.delete();
参数：无参数。
注意事项：调用后数据不可恢复，仅适用于脚本卸载、数据重置等特殊场景，常规数据清理建议使用 DELETE 语句删除表内数据，而非直接删除数据库。

（七）beginTransaction 与 endTransaction 方法

这两个方法成对使用，用于开启和结束数据库事务。事务是数据库的重要特性，可保证一组 SQL 语句要么全部执行成功，要么全部不执行，有效避免因脚本中断、设备卡顿导致的数据残缺问题。

开启事务：db.beginTransaction();
结束事务：db.endTransaction();
应用场景：适用于批量插入数据、多表联动修改等批量操作场景，提升数据一致性与脚本容错能力。

三、完整实战案例：自动化日志数据库搭建与使用

理论结合实践才能真正掌握用法，下面以自动化脚本运行日志存储为场景，编写一套完整可运行的冰狐脚本，涵盖数据库创建、数据表创建、数据插入、数据查询、资源释放全流程，代码基于官方示例优化，可直接在冰狐平台移动端脚本编辑器中调试运行。

本次案例需求：创建名为script_db的本地数据库，新建日志表run_log，用于记录脚本名称、运行时间、运行状态、异常信息；实现单条日志插入、全量日志查询、条件查询功能。

（一）完整脚本代码

javascript 复制代码

// 1. 初始化数据库实例，创建/打开名为 script_db 的本地数据库
var db = new Database('script_db');
console.log("数据库 script_db 打开成功");

// 2. 判断日志表 run_log 是否存在，不存在则创建数据表
if (!db.isTableExist('run_log')) {
    // 编写建表SQL：自增主键、脚本名称、运行时间、运行状态、异常信息
    var createTableSql = `create table run_log(
        id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
        script_name VARCHAR(50) NULL,
        run_time DATETIME(4) NULL,
        run_status VARCHAR(20) NULL,
        error_msg VARCHAR(200) NULL
    )`;
    // 执行建表语句
    var createResult = db.exeSql(createTableSql);
    if (createResult) {
        console.log("数据表 run_log 创建成功");
    } else {
        console.log("数据表创建失败，脚本终止");
        db.close(); // 异常时及时关闭数据库
        return;
    }
} else {
    console.log("数据表 run_log 已存在，无需重复创建");
}

// 3. 插入单条运行日志数据
var insertSql = `insert into run_log(script_name, run_time, run_status, error_msg)
values('APP数据采集脚本', '2026-06-17 10:20:00', '运行成功', '')`;
var insertResult = db.exeSql(insertSql);
if (insertResult) {
    console.log("日志数据插入成功");
} else {
    console.log("日志数据插入失败");
}

// 4. 全量查询数据表所有日志数据
var allLog = db.query('select * from run_log');
console.log("全部运行日志：", allLog);
// 遍历查询结果，解析每条日志
for (var i = 0; i < allLog.length; i++) {
    var logItem = allLog[i];
    console.log(`第${i+1}条日志：脚本名=${logItem.script_name}，运行状态=${logItem.run_status}`);
}

// 5. 条件查询：仅查询运行状态为"运行成功"的日志
var successLog = db.query("select script_name, run_time from run_log where run_status = '运行成功'");
console.log("成功运行的脚本日志：", successLog);

// 6. 所有数据库操作完成，关闭数据库连接，释放资源
db.close();
console.log("数据库连接已关闭");

（二）代码分步解读

数据库初始化 ：通过new Database('script_db')创建数据库实例，这是所有操作的起点，执行后本地生成对应的数据库文件。
数据表检测与创建 ：利用isTableExist判断表状态，搭配exeSql执行建表 SQL。表结构参考官方示例，设置自增主键id作为唯一标识，同时适配字符串、时间等常用数据类型。
数据插入 ：使用标准INSERT语句写入日志数据，通过exeSql返回值判断插入结果，便于脚本调试。
数据查询 ：两次调用query方法，分别实现全表查询与条件查询，查询结果为 JSON 数组，可通过循环遍历提取字段数据，用于后续逻辑判断。
资源释放 ：脚本最后调用close()关闭数据库连接，遵循资源释放规范。

（三）脚本运行方式

将上述代码复制到冰狐平台移动端脚本编辑器中，保存后点击在线调试，即可在日志控制台查看每一步执行结果。该脚本支持在线运行与离线打包运行，打包为纯本地 APK 后，数据依旧正常读写，完全适配离线自动化场景。

四、事务功能实战：批量数据插入

当脚本需要批量插入数十条甚至上百条数据时，单条执行 SQL 不仅效率低下，还容易出现部分数据插入成功、部分失败的情况。此时可使用数据库事务功能，将多条插入语句纳入同一个事务中，保证数据完整性。以下是批量数据插入的事务示例代码：

javascript 复制代码

var db = new Database('script_db');
// 开启事务
db.beginTransaction();
try {
    // 批量插入多条日志数据
    var sql1 = `insert into run_log(script_name, run_time, run_status) values('定时点击脚本', '2026-06-17 10:30:00', '运行成功')`;
    var sql2 = `insert into run_log(script_name, run_time, run_status) values('页面遍历脚本', '2026-06-17 10:35:00', '运行失败')`;
    db.exeSql(sql1);
    db.exeSql(sql2);
    // 所有语句执行完成，结束事务（提交事务）
    db.endTransaction();
    console.log("批量数据插入事务执行成功");
} catch (e) {
    // 出现异常时，事务自动回滚，所有插入操作失效
    console.log("批量插入异常，事务回滚：" + e);
    db.endTransaction();
}
db.close();

在该示例中，beginTransaction()开启事务后，两条插入语句视为一个整体。若其中任意一条语句报错、脚本中断，整个事务会自动回滚，不会产生残缺数据，极大提升了批量操作的稳定性。

五、数据修改与删除操作补充

除建表、增、查外，日常运维中还需要修改历史数据、删除无用数据，这两类操作同样通过exeSql方法执行标准 SQL 语句实现，示例如下：

更新表中数据

javascript 复制代码

var db = new Database('script_db');
// 修改指定ID日志的运行状态
var updateSql = "update run_log set run_status = '重新运行' where id = 1";
db.exeSql(updateSql);
db.close();

删除单条 / 多条数据

javascript 复制代码

var db = new Database('script_db');
// 删除运行失败的日志数据
var deleteSql = "delete from run_log where run_status = '运行失败'";
db.exeSql(deleteSql);
db.close();

重要提醒 ：DELETE语句会永久删除表内数据，执行前建议先通过query查询目标数据，确认无误后再执行删除操作。

六、常见问题与使用规范总结

（一）高频问题排查

SQL 语句执行失败，exeSql 返回 false大概率是 SQL 语法错误、数据表 / 字段名称拼写错误、字段类型不匹配。建议分步调试，先单独测试 SQL 语句，再嵌入脚本中。同时注意字符串字段内容不要包含特殊符号，避免 SQL 语法冲突。
查询结果为空先确认数据表中是否存在对应数据，再检查查询条件是否精准，区分大小写与字段名称。
脚本运行卡顿、内存占用高 核心原因是未调用close()关闭数据库连接。务必保证每一次打开数据库后，最终都执行关闭操作，避免连接堆积。
离线脚本打包后数据库失效 打包离线 APK 时，需在冰狐打包页面勾选纯本地运行选项，保证脚本完全脱离云端，本地数据库才能正常读写。

（二）最佳使用规范

命名规范：数据库名、表名、字段名尽量简洁易懂，统一命名规则，避免使用中文与特殊字符。
资源管理：遵循 "打开 - 操作 - 关闭" 流程，异常分支中也要关闭数据库。
事务使用：批量操作、多表联动操作强制使用事务，保障数据一致性。
数据安全：本地数据库存储敏感数据时，可结合脚本逻辑做简单加密，同时谨慎使用delete()方法删除数据库。
语句优化：大数据量查询时，合理使用limit关键字限制查询条数，减少内存消耗。

七、总结

对于自动化脚本开发者而言，合理运用本地数据库，不仅能解决日志记录、数据缓存、配置存储等基础需求，还能拓展脚本的业务能力，让简单的自动化操作升级为具备数据统计、状态追溯、循环迭代能力的完整自动化任务。在实际开发中，只需结合自身业务场景设计数据表结构，严格遵循 API 使用规范与 SQL 语法，就能充分发挥本地数据库的价值，打造更稳定、更实用的移动端自动化脚本。