做按键精灵脚本开发，批量读取、筛选、处理本地文件是刚需：批量识别 APK、统一重命名图片、清理缓存日志、检索脚本资源…… 很多新手还在用复杂循环、模拟查找文件的低效写法，代码冗长、兼容性差。 按键精灵官方内置lfs.lua文件插件，核心命令lfs.ScanPath提供标准化目录遍历能力，同时兼容安卓、iOS 双端，支持筛选文件 / 文件夹、递归深度自定义，仅几行代码就能读取目录全部内容，大幅简化文件自动化逻辑，是脚本开发者必备底层工具。

开发痛点：传统文件遍历方案短板明显

1. 跨端适配困难：安卓、iOS 原生文件接口不统一，分开写两套遍历逻辑，维护成本翻倍；

2. 功能单一：第三方遍历命令大多只能读取文件，无法区分文件夹、不支持递归子目录；

3. 参数简陋：不能限制遍历层级，深层目录遍历易卡顿、溢出；

4. 代码冗余：多层循环嵌套判断文件 / 文件夹，可读性差，报错排查困难。 官方 lfs.ScanPath 针对以上问题做完整封装，全参数可控，原生稳定无兼容 bug。

lfs.ScanPath 命令完整参数详解（官方标准文档）

基础信息

命令：lfs.ScanPath

功能：遍历指定存储目录，返回文件名 / 文件夹名数组，支持精准筛选、递归扫描、层级限制

前置调用：Import "lfs.lua"

参数完整说明

参数名	参数类型	是否必选	参数说明
dir	string	是	遍历目录的路径，支持相对路径和绝对路径 相对路径：在使用 lfs.Chdir 设置了工作路径后，可以传入相对路径（路径开头不能有 /），例如：a/b/c 绝对路径：直接传入想要遍历的目录的绝对路径，例如：/sdcard/com.cyjh.mobileanjian/a/b
mode	int	否	遍历的类型： 1：只遍历文件 2：只遍历目录 3：遍历文件以及目录（默认值）
deep	bool	否	是否递归遍历子目录，默认 false，仅遍历当前目录
maxDepth	int	否	最大递归遍历层级，默认20，只有在 deep 参数为 true 时生效

返回值

一维数组，存储目录内所有匹配的文件 / 文件夹名称，可通过For Each循环批量读取处理。

返回名	返回类型	返回说明
result	table	根据 mode 参数返回包含文件或者子目录的完整路径数组

代码范例

Import "lfs.lua"

Dim tbl, rootDir
rootDir = GetTempDir()
// 递归遍历文件
TracePrint "--------- 只遍历文件 ---------"
tbl = lfs.ScanPath(rootDir, 1, false)
For Each k , v In tbl
    TracePrint k, v
Next

// 递归遍历目录
TracePrint "--------- 只遍历目录 ---------"
tbl = lfs.ScanPath(rootDir, 2, true)
For Each k , v In tbl
    TracePrint k, v
Next

// 递归遍历文件和目录
TracePrint "--------- 遍历文件/目录 ---------"
tbl = lfs.ScanPath(rootDir, 3, true)
For Each k , v In tbl
    TracePrint k, v
Next

// 限定递归的深度
TracePrint "--------- 限定深度 ---------"
tbl = lfs.ScanPath(rootDir, 3, true, 2)
For Each k , v In tbl
    TracePrint k, v
Next

五大主流落地应用场景

1. 批量 APK 自动安装

遍历 Download 下载目录，筛选后缀.apk文件，搭配安装命令实现批量静默装包，适配任务试玩、云手机群控脚本。

2. 图片批量统一重命名

遍历相册目录，循环读取图片文件，自动批量重命名为 Pic_01、Pic_02 标准化格式。

3. 脚本资源自动释放部署

脚本附件释放工具包至本地文件夹，ScanPath 遍历全部依赖安装包，自动完成初始化部署。

4. 缓存 / 日志批量清理

递归扫描缓存目录，匹配日志、临时文件后缀，批量删除过期文件，释放设备存储空间。

5. 本地资源检索匹配

递归遍历多层资源文件夹，检索指定后缀 txt/json 配置文件，自动读取脚本配置参数。

相比第三方遍历命令的核心优势

1. 官方原生稳定：lfs 为按键精灵官方认证插件，持续迭代修复系统目录遍历报错，无第三方插件未知风险；

2. 双端通用：安卓、iOS 一套代码通用，无需区分设备系统适配；

3. 精细化可控：自由切换文件 / 文件夹 / 全部模式，递归开关、层级限制双重防卡顿；

4. 配套完整文件生态：同插件支持创建文件夹、删除目录、读取文件属性、修改文件时间，一套插件搞定全文件操作；

5. 低资源占用：底层封装轻量化，遍历万级文件无明显延迟，适配模拟器、低配云手机。

新手使用避坑指南

1. 路径规范：统一使用GetSdcardDir()拼接存储路径，不要硬写/sdcard/，适配高版本安卓存储权限；

2. 递归慎用：遍历系统根目录、海量文件夹时关闭递归，或缩小层级参数，避免脚本卡死；

3. 空目录判断：遍历后增加数组长度判断，无文件时直接跳过后续操作，减少报错；

lfs.ScanPath 是按键精灵文件自动化的底层核心命令，用极简代码替代复杂文件检索逻辑，兼顾稳定性、扩展性与跨平台适配。无论是个人开发挂机脚本、工作室批量群控设备，还是自动化测试、本地资源批量处理，都能大幅降低代码量、提升脚本运行稳定性，是每一位按键精灵开发者必须掌握的基础工具。