简介js-filesearch 是一个基于 Node.js 与 JavaScript 的文件搜索项目面向希望掌握服务端 JavaScript 文件操作、提升目录遍历与检索能力的开发者尤其适合作为 Node.js 入门后的进阶练习素材。压缩包共 9 个文件以 5 个 js 源码文件为核心辅以 package.json 依赖配置、README 说明文档、LICENSE 授权文件及 .gitignore 等整体仅约 4KB结构轻量、便于快速通读。项目围绕 fs 模块读取目录、path 路径拼接、异步流程控制与文件名匹配等环节展开并可能涉及命令行参数解析与单元测试思路读者可从中理解非阻塞 I/O 模型下搜索工具的实现脉络。目前已有 292 人学习下载适合想通过小型实战项目巩固 JavaScript 文件系统操作与模块化组织方式的开发者参考。1. 文件夹里翻文件为什么我最后写了个 Node.js 小工具上周帮同事找一个三个月前的配置文件Windows 资源管理器转了三圈没结果Everything 又没装最后靠dir /s /b | findstr硬扛。这种场景其实很常见临时接手一个几十 GB 的项目目录想按文件名、扩展名或者模糊片段定位某个文件系统自带搜索要么慢要么索引没建好。js-filesearch 就是冲着这个痛点来的——一个用 JavaScript 写的 Node.js 文件夹搜索项目核心逻辑不复杂但把递归遍历、条件过滤、结果输出这几件事拆得比较干净。它适合两类人一是日常要在杂乱目录里捞文件的开发者二是想拿一个真实可跑的小项目练手 Node.js 文件系统 API 的人。下面我按「它怎么组织、怎么跑起来、参数怎么调、哪里会翻车」的顺序拆一遍。2. 拆开 js-filesearch递归遍历与过滤链路是怎么搭的2.1 目录遍历的两种写法与选型理由Node.js 里遍历文件夹绕不开fs模块。常见做法有两套一套是fs.readdirSync配递归函数同步阻塞但代码直白另一套是fs.promises.readdir配async/await异步不阻塞事件循环。js-filesearch 这类工具我一般倾向异步版本原因很实际搜索大目录时同步递归会把主线程卡死命令行看起来像假死用户以为程序挂了。异步写法虽然多几行await但能在遍历过程中输出进度体验差别很大。核心遍历逻辑大致是这样组织的const fs require(fs).promises; const path require(path); // 递归收集目录下所有文件路径 async function walk(dir, results []) { let entries; try { entries await fs.readdir(dir, { withFileTypes: true }); } catch (err) { // 权限不足的目录直接跳过不让整个搜索中断 if (err.code EACCES || err.code EPERM) return results; throw err; } for (const entry of entries) { const fullPath path.join(dir, entry.name); if (entry.isDirectory()) { await walk(fullPath, results); // 目录继续下钻 } else if (entry.isFile()) { results.push(fullPath); // 文件收进结果集 } } return results; }这段代码有三个关键点值得说。第一withFileTypes: true让readdir直接返回Dirent对象省掉对每个条目再调一次stat判断类型目录大时能少一半系统调用。第二try/catch包住readdir而不是包住整个递归是为了让单个无权限目录只影响自己不把整棵树带崩——这是实际跑系统目录时最容易忽略的地方。第三path.join而不是字符串拼接避免 Windows 反斜杠和 POSIX 斜杠混用导致的路径匹配失败。2.2 文件名匹配从精确到模糊的三层过滤搜到文件只是第一步真正决定好不好用的是匹配策略。js-filesearch 这类项目通常支持三种粒度精确文件名、扩展名过滤、子串或正则模糊匹配。我一般把它们做成一条过滤链先便宜后昂贵减少不必要的计算function createMatcher({ name, ext, keyword, useRegex }) { return (filePath) { const base path.basename(filePath); if (name base ! name) return false; // 精确名最快 if (ext path.extname(base).toLowerCase() ! ext.toLowerCase()) return false; if (keyword) { if (useRegex) { return new RegExp(keyword, i).test(base); // 正则最灵活也最慢 } return base.toLowerCase().includes(keyword.toLowerCase()); } return true; }; }参数含义需要说清楚name是全名精确匹配适合你知道文件叫config.json但不知道在哪个子目录ext只比对扩展名注意统一转小写否则.PNG和.png会漏keyword是子串匹配useRegex打开后按正则处理适合^log-\d{4}这种模式。过滤链的顺序不是随便排的——精确名和扩展名都是 O(1) 级别比较正则每次都要编译执行放最后能显著降低大目录下的总耗时。这里有个容易翻车的点正则里的特殊字符如果来自用户输入得先转义不然一个(就能让new RegExp抛异常整个搜索直接退出。2.3 结果输出与命令行参数设计搜到结果后怎么呈现决定了这个工具是「能用」还是「好用」。最朴素的是每行打印一个绝对路径但路径一长终端就折行肉眼很难扫。我习惯在输出里带上相对路径和文件大小必要时加一个--json开关方便管道给其他脚本function formatResult(filePath, rootDir, stats) { const rel path.relative(rootDir, filePath); const size (stats.size / 1024).toFixed(1) KB; return ${rel}\t${size}; } // 主流程里收集结果时顺带取 stat const stat await fs.stat(fullPath); console.log(formatResult(fullPath, rootDir, stat));命令行参数用process.argv手动解析就够不必上重型框架。典型调用形态是node search.js 目录 --ext .js --keyword user。参数解析时要注意目录参数必须校验存在性fs.access一下再进递归否则用户打错路径会得到一个空结果而不是明确报错这种「静默失败」最让人抓狂。另外--json模式下不要混入任何进度提示文本否则下游JSON.parse直接崩这是血泪经验。3. 跑起来从零复现一次完整搜索3.1 环境准备与项目结构确认动手前先确认 Node 版本。这类项目一般要求 Node 14 以上因为用到了fs.promises和可选链。用node -v看一眼低于 14 就先升级不然readdir的withFileTypes行为会有差异。项目结构通常很扁平入口search.js或index.js可能有一个lib/放遍历和匹配逻辑package.json里一般没有重依赖npm install跑不跑都行。我习惯先cat package.json看main和scripts确认入口文件和有没有测试脚本再决定是直接node跑还是走npm start。如果项目带bin字段可以npm link把它挂到全局之后就能像普通命令一样调用。不挂全局也没关系node ./search.js一样跑只是每次要带路径。这一步别急着改代码先按默认参数跑一次看输出格式和预期是否一致心里有个基线再动刀。3.2 基础搜索按扩展名和关键词定位文件假设要在某个项目目录里找所有 JavaScript 文件并且文件名带user# 基础用法指定根目录按扩展名和关键词过滤 node search.js ./my-project --ext .js --keyword user # 只看结果数量不打印明细 node search.js ./my-project --ext .js --keyword user --count # 输出 JSON方便接 jq 或写进脚本 node search.js ./my-project --ext .js --keyword user --json | jq .[]第一条命令的./my-project是搜索根目录--ext .js限定扩展名--keyword user做子串匹配。执行后应该看到类似src/utils/userHelper.js 3.2 KB的行。如果结果为空先别怀疑代码按顺序排查目录路径对不对、扩展名有没有带点、关键词大小写是否被-i之类的开关影响。第二条--count适合在 CI 或脚本里判断「有没有匹配」只关心数量时能省掉大量终端输出。第三条配合jq是熟手常用姿势把搜索结果当数据流处理比肉眼扫强得多。3.3 进阶调用正则匹配与结果重定向文件名有规律但记不全时正则就派上用场了。比如找所有以log-开头、后面跟四位数字的文件# 正则模式注意 shell 里用单引号包住避免 $ 被提前展开 node search.js ./logs --keyword ^log-\d{4} --regex # 结果重定向到文件便于后续比对 node search.js ./src --ext .ts --json ts-files.json # 排除 node_modules避免噪音若项目支持 --exclude node search.js . --ext .js --exclude node_modules --exclude dist正则那条命令里单引号很关键双引号下\d和$可能被 shell 解释导致传给 Node 的模式已经变形。重定向那条把 JSON 落盘后续可以用jq length数数量或者 diff 两次搜索结果看目录变化。--exclude是实际使用中频率极高的参数node_modules、dist、.git这三个目录不排除搜索结果里一半是噪音。如果项目没实现--exclude可以在遍历函数里加一个目录名黑名单判断改动量很小收益很大。4. 避坑与排查这类搜索工具最容易翻车的五处4.1 现象搜索大目录时命令行像卡死原因通常是用了同步递归readdirSync或者异步但没做任何进度反馈主线程被大量stat调用拖住。解决方式是改用fs.promises.readdir异步遍历并在每处理 N 个目录时打印一次进度到stderr这样既不污染stdout的结果输出又能让用户知道程序还活着。如果目录实在太大考虑加一个最大深度参数先限制范围再逐步放开。4.2 现象结果里出现重复路径或漏掉文件重复多半是符号链接导致的循环引用a - b - a这种结构会让递归无限下钻。解决方式是在Dirent判断里跳过isSymbolicLink()的条目或者维护一个已访问 inode 集合。漏文件则常见于权限问题被静默吞掉——EACCES被 catch 后直接 return用户完全不知道哪些目录没搜到。稳妥做法是收集跳过的目录列表结束时在stderr汇总提示别让「没搜到」和「没权限搜」混为一谈。4.3 现象Windows 下路径匹配全部失效原因是代码里硬编码了/做分隔符或者用字符串startsWith比较路径。Windows 返回的是反斜杠path.join出来的路径和手写的/对不上。统一用path.join、path.resolve、path.relative处理路径比较时先path.normalize。另外扩展名比较记得toLowerCase()Windows 文件名大小写不敏感但字符串比较是敏感的.JS和.js会漏。4.4 现象正则关键词让程序直接抛异常退出用户输入的keyword里带(、[、*这类正则元字符new RegExp编译失败异常没被捕获整个进程挂掉。解决方式是在--regex模式下用try/catch包住new RegExp失败时给出明确提示「正则语法错误」而不是堆栈。更稳的做法是提供一个--literal开关默认按字面量匹配用户显式要求才走正则降低误用概率。4.5 现象--json输出被进度信息污染前面提过console.log的进度提示和 JSON 结果混在stdout下游解析直接失败。根因是没区分输出通道。约定是结果走stdout进度、警告、错误走stderr。Node 里用console.error或process.stderr.write输出提示console.log只留给最终结果。这个约定一旦定下来管道组合就顺了| jq也不会再报Unexpected token。5. 把它用顺手的几个进阶技巧真正让这类小工具产生复利的是「组合」而不是「单次搜索」。我习惯把常用搜索固化成 shell 函数或 npm script比如在package.json里加一条find:js: node search.js . --ext .js --exclude node_modules之后npm run find:js -- --keyword user就能带参调用省去每次敲长路径。再进一步把--json输出接到jq做二次筛选比如按文件大小排序取前十个node search.js ./src --ext .js --json \ | jq -r .[] | \(.size)\t\(.path) \ | sort -rn | head -10这条命令先拿 JSON再用jq拼成「大小 路径」的制表符分隔行sort -rn按数值倒序head取前十。找「哪个文件异常大」时特别管用比一个个ls -lh快得多。参数上要注意jq的字段名得和项目实际输出对齐如果项目输出的是filePath而不是path改一下字段名即可别硬套。另一个技巧是给搜索加「时间窗」过滤。很多项目只实现了名字匹配但实际排查时经常要找「最近三天改过的文件」。在遍历拿到stat后加一个mtime判断就行const cutoff Date.now() - 3 * 24 * 60 * 60 * 1000; if (stat.mtimeMs cutoff) return; // 早于三天前的跳过mtimeMs是毫秒时间戳比mtime的 Date 对象比较更直接。这个改动很小但把工具从「找名字」升级成「找变化」排查构建产物、临时文件时价值很高。最后说个验证习惯每次改完遍历或匹配逻辑我都会先在一个已知结构的小目录上跑一遍用--count核对数量再放到大目录上跑。有次偷懒跳过这步正则里一个贪婪匹配把整个node_modules都捞了出来终端刷了几千行才反应过来。从那以后改完匹配逻辑先小目录验数、再大目录实战成了固定动作。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/26 20:08:50 · 阅读 1.2k Node.js文件夹搜索工具：递归遍历与过滤链实战
简介js-filesearch 是一个基于 Node.js 与 JavaScript 的文件搜索项目面向希望掌握服务端 JavaScript 文件操作、提升目录遍历与检索能力的开发者尤其适合作为 Node.js 入门后的进阶练习素材。压缩包共 9 个文件以 5 个 js 源码文件为核心辅以 package.json 依赖配置、README 说明文档、LICENSE 授权文件及 .gitignore 等整体仅约 4KB结构轻量、便于快速通读。项目围绕 fs 模块读取目录、path 路径拼接、异步流程控制与文件名匹配等环节展开并可能涉及命令行参数解析与单元测试思路读者可从中理解非阻塞 I/O 模型下搜索工具的实现脉络。目前已有 292 人学习下载适合想通过小型实战项目巩固 JavaScript 文件系统操作与模块化组织方式的开发者参考。1. 文件夹里翻文件为什么我最后写了个 Node.js 小工具上周帮同事找一个三个月前的配置文件Windows 资源管理器转了三圈没结果Everything 又没装最后靠dir /s /b | findstr硬扛。这种场景其实很常见临时接手一个几十 GB 的项目目录想按文件名、扩展名或者模糊片段定位某个文件系统自带搜索要么慢要么索引没建好。js-filesearch 就是冲着这个痛点来的——一个用 JavaScript 写的 Node.js 文件夹搜索项目核心逻辑不复杂但把递归遍历、条件过滤、结果输出这几件事拆得比较干净。它适合两类人一是日常要在杂乱目录里捞文件的开发者二是想拿一个真实可跑的小项目练手 Node.js 文件系统 API 的人。下面我按「它怎么组织、怎么跑起来、参数怎么调、哪里会翻车」的顺序拆一遍。2. 拆开 js-filesearch递归遍历与过滤链路是怎么搭的2.1 目录遍历的两种写法与选型理由Node.js 里遍历文件夹绕不开fs模块。常见做法有两套一套是fs.readdirSync配递归函数同步阻塞但代码直白另一套是fs.promises.readdir配async/await异步不阻塞事件循环。js-filesearch 这类工具我一般倾向异步版本原因很实际搜索大目录时同步递归会把主线程卡死命令行看起来像假死用户以为程序挂了。异步写法虽然多几行await但能在遍历过程中输出进度体验差别很大。核心遍历逻辑大致是这样组织的const fs require(fs).promises; const path require(path); // 递归收集目录下所有文件路径 async function walk(dir, results []) { let entries; try { entries await fs.readdir(dir, { withFileTypes: true }); } catch (err) { // 权限不足的目录直接跳过不让整个搜索中断 if (err.code EACCES || err.code EPERM) return results; throw err; } for (const entry of entries) { const fullPath path.join(dir, entry.name); if (entry.isDirectory()) { await walk(fullPath, results); // 目录继续下钻 } else if (entry.isFile()) { results.push(fullPath); // 文件收进结果集 } } return results; }这段代码有三个关键点值得说。第一withFileTypes: true让readdir直接返回Dirent对象省掉对每个条目再调一次stat判断类型目录大时能少一半系统调用。第二try/catch包住readdir而不是包住整个递归是为了让单个无权限目录只影响自己不把整棵树带崩——这是实际跑系统目录时最容易忽略的地方。第三path.join而不是字符串拼接避免 Windows 反斜杠和 POSIX 斜杠混用导致的路径匹配失败。2.2 文件名匹配从精确到模糊的三层过滤搜到文件只是第一步真正决定好不好用的是匹配策略。js-filesearch 这类项目通常支持三种粒度精确文件名、扩展名过滤、子串或正则模糊匹配。我一般把它们做成一条过滤链先便宜后昂贵减少不必要的计算function createMatcher({ name, ext, keyword, useRegex }) { return (filePath) { const base path.basename(filePath); if (name base ! name) return false; // 精确名最快 if (ext path.extname(base).toLowerCase() ! ext.toLowerCase()) return false; if (keyword) { if (useRegex) { return new RegExp(keyword, i).test(base); // 正则最灵活也最慢 } return base.toLowerCase().includes(keyword.toLowerCase()); } return true; }; }参数含义需要说清楚name是全名精确匹配适合你知道文件叫config.json但不知道在哪个子目录ext只比对扩展名注意统一转小写否则.PNG和.png会漏keyword是子串匹配useRegex打开后按正则处理适合^log-\d{4}这种模式。过滤链的顺序不是随便排的——精确名和扩展名都是 O(1) 级别比较正则每次都要编译执行放最后能显著降低大目录下的总耗时。这里有个容易翻车的点正则里的特殊字符如果来自用户输入得先转义不然一个(就能让new RegExp抛异常整个搜索直接退出。2.3 结果输出与命令行参数设计搜到结果后怎么呈现决定了这个工具是「能用」还是「好用」。最朴素的是每行打印一个绝对路径但路径一长终端就折行肉眼很难扫。我习惯在输出里带上相对路径和文件大小必要时加一个--json开关方便管道给其他脚本function formatResult(filePath, rootDir, stats) { const rel path.relative(rootDir, filePath); const size (stats.size / 1024).toFixed(1) KB; return ${rel}\t${size}; } // 主流程里收集结果时顺带取 stat const stat await fs.stat(fullPath); console.log(formatResult(fullPath, rootDir, stat));命令行参数用process.argv手动解析就够不必上重型框架。典型调用形态是node search.js 目录 --ext .js --keyword user。参数解析时要注意目录参数必须校验存在性fs.access一下再进递归否则用户打错路径会得到一个空结果而不是明确报错这种「静默失败」最让人抓狂。另外--json模式下不要混入任何进度提示文本否则下游JSON.parse直接崩这是血泪经验。3. 跑起来从零复现一次完整搜索3.1 环境准备与项目结构确认动手前先确认 Node 版本。这类项目一般要求 Node 14 以上因为用到了fs.promises和可选链。用node -v看一眼低于 14 就先升级不然readdir的withFileTypes行为会有差异。项目结构通常很扁平入口search.js或index.js可能有一个lib/放遍历和匹配逻辑package.json里一般没有重依赖npm install跑不跑都行。我习惯先cat package.json看main和scripts确认入口文件和有没有测试脚本再决定是直接node跑还是走npm start。如果项目带bin字段可以npm link把它挂到全局之后就能像普通命令一样调用。不挂全局也没关系node ./search.js一样跑只是每次要带路径。这一步别急着改代码先按默认参数跑一次看输出格式和预期是否一致心里有个基线再动刀。3.2 基础搜索按扩展名和关键词定位文件假设要在某个项目目录里找所有 JavaScript 文件并且文件名带user# 基础用法指定根目录按扩展名和关键词过滤 node search.js ./my-project --ext .js --keyword user # 只看结果数量不打印明细 node search.js ./my-project --ext .js --keyword user --count # 输出 JSON方便接 jq 或写进脚本 node search.js ./my-project --ext .js --keyword user --json | jq .[]第一条命令的./my-project是搜索根目录--ext .js限定扩展名--keyword user做子串匹配。执行后应该看到类似src/utils/userHelper.js 3.2 KB的行。如果结果为空先别怀疑代码按顺序排查目录路径对不对、扩展名有没有带点、关键词大小写是否被-i之类的开关影响。第二条--count适合在 CI 或脚本里判断「有没有匹配」只关心数量时能省掉大量终端输出。第三条配合jq是熟手常用姿势把搜索结果当数据流处理比肉眼扫强得多。3.3 进阶调用正则匹配与结果重定向文件名有规律但记不全时正则就派上用场了。比如找所有以log-开头、后面跟四位数字的文件# 正则模式注意 shell 里用单引号包住避免 $ 被提前展开 node search.js ./logs --keyword ^log-\d{4} --regex # 结果重定向到文件便于后续比对 node search.js ./src --ext .ts --json ts-files.json # 排除 node_modules避免噪音若项目支持 --exclude node search.js . --ext .js --exclude node_modules --exclude dist正则那条命令里单引号很关键双引号下\d和$可能被 shell 解释导致传给 Node 的模式已经变形。重定向那条把 JSON 落盘后续可以用jq length数数量或者 diff 两次搜索结果看目录变化。--exclude是实际使用中频率极高的参数node_modules、dist、.git这三个目录不排除搜索结果里一半是噪音。如果项目没实现--exclude可以在遍历函数里加一个目录名黑名单判断改动量很小收益很大。4. 避坑与排查这类搜索工具最容易翻车的五处4.1 现象搜索大目录时命令行像卡死原因通常是用了同步递归readdirSync或者异步但没做任何进度反馈主线程被大量stat调用拖住。解决方式是改用fs.promises.readdir异步遍历并在每处理 N 个目录时打印一次进度到stderr这样既不污染stdout的结果输出又能让用户知道程序还活着。如果目录实在太大考虑加一个最大深度参数先限制范围再逐步放开。4.2 现象结果里出现重复路径或漏掉文件重复多半是符号链接导致的循环引用a - b - a这种结构会让递归无限下钻。解决方式是在Dirent判断里跳过isSymbolicLink()的条目或者维护一个已访问 inode 集合。漏文件则常见于权限问题被静默吞掉——EACCES被 catch 后直接 return用户完全不知道哪些目录没搜到。稳妥做法是收集跳过的目录列表结束时在stderr汇总提示别让「没搜到」和「没权限搜」混为一谈。4.3 现象Windows 下路径匹配全部失效原因是代码里硬编码了/做分隔符或者用字符串startsWith比较路径。Windows 返回的是反斜杠path.join出来的路径和手写的/对不上。统一用path.join、path.resolve、path.relative处理路径比较时先path.normalize。另外扩展名比较记得toLowerCase()Windows 文件名大小写不敏感但字符串比较是敏感的.JS和.js会漏。4.4 现象正则关键词让程序直接抛异常退出用户输入的keyword里带(、[、*这类正则元字符new RegExp编译失败异常没被捕获整个进程挂掉。解决方式是在--regex模式下用try/catch包住new RegExp失败时给出明确提示「正则语法错误」而不是堆栈。更稳的做法是提供一个--literal开关默认按字面量匹配用户显式要求才走正则降低误用概率。4.5 现象--json输出被进度信息污染前面提过console.log的进度提示和 JSON 结果混在stdout下游解析直接失败。根因是没区分输出通道。约定是结果走stdout进度、警告、错误走stderr。Node 里用console.error或process.stderr.write输出提示console.log只留给最终结果。这个约定一旦定下来管道组合就顺了| jq也不会再报Unexpected token。5. 把它用顺手的几个进阶技巧真正让这类小工具产生复利的是「组合」而不是「单次搜索」。我习惯把常用搜索固化成 shell 函数或 npm script比如在package.json里加一条find:js: node search.js . --ext .js --exclude node_modules之后npm run find:js -- --keyword user就能带参调用省去每次敲长路径。再进一步把--json输出接到jq做二次筛选比如按文件大小排序取前十个node search.js ./src --ext .js --json \ | jq -r .[] | \(.size)\t\(.path) \ | sort -rn | head -10这条命令先拿 JSON再用jq拼成「大小 路径」的制表符分隔行sort -rn按数值倒序head取前十。找「哪个文件异常大」时特别管用比一个个ls -lh快得多。参数上要注意jq的字段名得和项目实际输出对齐如果项目输出的是filePath而不是path改一下字段名即可别硬套。另一个技巧是给搜索加「时间窗」过滤。很多项目只实现了名字匹配但实际排查时经常要找「最近三天改过的文件」。在遍历拿到stat后加一个mtime判断就行const cutoff Date.now() - 3 * 24 * 60 * 60 * 1000; if (stat.mtimeMs cutoff) return; // 早于三天前的跳过mtimeMs是毫秒时间戳比mtime的 Date 对象比较更直接。这个改动很小但把工具从「找名字」升级成「找变化」排查构建产物、临时文件时价值很高。最后说个验证习惯每次改完遍历或匹配逻辑我都会先在一个已知结构的小目录上跑一遍用--count核对数量再放到大目录上跑。有次偷懒跳过这步正则里一个贪婪匹配把整个node_modules都捞了出来终端刷了几千行才反应过来。从那以后改完匹配逻辑先小目录验数、再大目录实战成了固定动作。希望帮到你。本文还有配套的精品资源点击获取