简介这是一套用于在文件夹中搜索文件的 Node.js (JavaScript) 项目面向需要提升文件操作与命令行工具开发能力的初学者。压缩包共 9 个文件大小仅 4KB其中以 JavaScript 源码为主辅以 JSON 配置清单、Markdown 使用说明与许可证文件结构紧凑适合逐文件拆读。项目中js 文件负责目录遍历、文件名匹配与搜索逻辑通过研读源码可以学习文件系统模块中目录读取、状态查询、文件读写等接口的用法掌握 path 路径拼接与解析、回调函数与 Promise/async/await 异步编程、正则或 glob 匹配规则以及用 Mocha、Chai 编写单元测试。此外还能理解事件驱动与非阻塞 I/O 模型弄明白命令行参数如何传入并构建可交互的命令行接口为日后编写文件管理类工具打下基础。目前已有 290 人学习下载值得作为快速上手 Node.js 文件系统的实践样例。1. js-filesearch 在解决什么问题给“在文件夹里找文件”这个需求一个 Node.js 答案一个塞满依赖的工程目录里你只记得某个配置文件的片段名字系统自带搜索索引还没跟上IDE 的全局搜索转圈十几秒。这时候在命令行里敲find到了 Windows 上又未必顺手临时用fs.readdirSync糊一个递归搜完才发现把node_modules整个遍历了一遍。这就是 js-filesearch 要处理的场景用 Node.js (JavaScript) 实现一个在文件夹内部搜文件的工具给定根目录和名字条件返回匹配文件列表。它不追求花哨功能核心就三条怎么遍历目录、怎么匹配文件名、在遍历之前要忽略掉哪些目录。适合自动化脚本、CI 里的文件检查、编辑器命令、批量整理文件的场景。要把它做得能交出去至少要绕过四个坑也就是下文要展开的遍历选型、并发控制、路径分隔符和符号链接。2. 在 Node.js 里搜文件有四条路线fs 递归、glob 模式、find 命令和 rg 引擎怎么选很多人以为“搜文件”就是个readdir循环实际上不同的实现路线在跨平台、速度、依赖体积上差别非常大。我这里先把四条路线摆出来每一条都对应不同的落地场景。2.1 用 fs.readdir 递归零依赖、可控性最强最朴素的方案是fs.readdir递归遍历目录拿到所有文件路径再逐个匹配文件名。这是 js-filesearch 这类项目最常用的基础实现因为不需要引入任何第三方依赖所有行为都是自己控制的。const fs require(fs); const path require(path); async function walk(dir, fileList []) { const entries await fs.promises.readdir(dir, { withFileTypes: true }); for (const entry of entries) { const fullPath path.join(dir, entry.name); if (entry.isDirectory()) { await walk(fullPath, fileList); } else if (entry.isFile()) { fileList.push(fullPath); } } return fileList; }这段代码的逻辑很直白readdir加上withFileTypes: true后每个 entry 会带上isDirectory()和isFile()方法不用对每个路径再发一次statIO 省了一半。entry.isDirectory()为真就继续向下递归entry.isFile()为真就把绝对路径收集起来。选这条路的关键原因是可控性忽略规则比如跳过node_modules、符号链接策略、最大深度限制全部能按自己的需求写在递归循环里。缺点也很明显匹配逻辑、忽略规则都要自己实现一个写不好就是后续要讲的几个坑的来源。2.2 用 glob 模式匹配表达力最好适合已知模式glob 模式匹配就是把**/*.test.js、src/**/*.spec.js这类带通配符的模式转换成对应的匹配逻辑由第三方库在背后帮你遍历。这是很多构建工具内部的文件筛选手法。// 示意使用某个 glob 实现 const glob require(some-glob-lib); const files await glob(src/**/*.test.js, { ignore: [**/node_modules/**], dot: false, });glob 的核心价值是表达力你想找“所有src下的测试文件”一行模式就写完了比手写正则去拼路径直观得多。它的匹配发生在路径层面而不是单纯文件名所以能精准表达“目录结构 文件名”的组合条件。选这条路时要注意glob 库一般自己也维护一套遍历逻辑遇到超大目录时同样存在并发控制的问题另外**的匹配行为和node_modules是否默认排除不同实现差异很大配置前一定要看对应库的文档不要指望默认行为符合预期。我一般会在项目对外的脚本里用 glob 写搜索条件而在工具内部也就是要给用户暴露底层 API 的时候仍然用 fs 递归。2.3 调系统 find快但跨平台是硬伤在 Linux 和 macOS 上find命令本身的执行效率很高实现上也极其简单直接用child_process把命令发出去接管输出。const { execFile } require(child_process); function findByFind(rootDir, pattern) { return new Promise((resolve, reject) { execFile(find, [rootDir, -type, f, -name, pattern], { maxBuffer: 1024 * 1024 * 16, }, (err, stdout) { if (err) return reject(err); resolve(stdout.trim().split(\n).filter(Boolean)); }); }); }find的方案在 Unix 系系统上又快又稳-name参数本身支持通配符几乎不用写匹配逻辑。但跨平台是它的硬伤Windows 的 cmd 和 PowerShell 都没有原生的find命令Windows 自带的find和 Unix 的find完全不是一回事要兼容就得检测平台后切换到where或者写 PowerShell 脚本那维护成本就上来了。所以这个方案我只在明确知道运行环境是 Linux/macOS 时才采用比如自己服务器上的运维脚本。对于要分发给团队、跨平台运行的 CLI这条路基本不考虑。2.4 用 rg 引擎速度天花板高代价是要背一个二进制追求极致搜索速度的场景比如在几十万文件的 monorepo 里搜文件纯 Node 遍历的性能天花板有限。常见做法是引入 ripgrep 这类底层引擎通过child_process调用让它输出文件路径Node 只负责解析结果。const { execFile } require(child_process); function findByRg(rootDir, pattern) { return new Promise((resolve, reject) { execFile(rg, [--files, rootDir, --glob, pattern], { maxBuffer: 1024 * 1024 * 32, }, (err, stdout) { if (err) return reject(err); resolve(stdout.trim().split(\n).filter(Boolean)); }); }); }rg 这类引擎默认就会遵守.gitignore还会跳过隐藏目录和二进制文件这是纯 Node 实现很难做到的细节。代价也很现实用户机器上必须装这个二进制否则就要在 npm 依赖里捆绑对应平台的二进制包安装体积直接变大。所以这个方案适合大目录的专业工具不适合轻量级的脚本。2.5 选型对比表方案跨平台依赖体积性能可控性适用场景fs 递归完全跨平台零依赖中最强工具内部实现、自定义规则多glob 模式看实现小中中已知模式的批量筛选调系统 find仅 Unix零依赖快弱服务器脚本、确定环境rg 引擎需捆绑二进制大最快中超大目录、专业 CLI3. 用 fs 递归加正则实现最小可用搜索核心循环与匹配设计上一章讲了选型这一章落地。我比较推荐的做法是底层用 fs 递归作为主干对外提供字符串匹配、正则匹配、通配符匹配三种条件。这套组合能覆盖 js-filesearch 标题要求的 90% 使用场景而且不引入额外依赖。3.1 定义 walk 遍历深度优先递归的核心循环遍历函数是搜索工具的心脏。在 2.1 的基础上我一般会加上三个关键参数最大深度maxDepth、符号链接开关followSymlinks、自定义忽略函数shouldIgnore。const fs require(fs); const path require(path); async function walk(dir, options {}) { const { maxDepth Infinity, followSymlinks false, shouldIgnore () false, } options; const results []; const visited new Set(); async function visit(currentDir, depth) { if (depth maxDepth) return; // 用 realpath 计数避免符号链接循环导致的死循环 const real await fs.promises.realpath(currentDir); if (visited.has(real)) return; visited.add(real); let entries; try { entries await fs.promises.readdir(currentDir, { withFileTypes: true }); } catch (err) { // 权限不足的目录直接跳过不能中断整个搜索 if (err.code EACCES || err.code EPERM) return; throw err; } for (const entry of entries) { const fullPath path.join(currentDir, entry.name); if (shouldIgnore(entry.name, fullPath)) continue; if (entry.isDirectory()) { await visit(fullPath, depth 1); } else if (entry.isFile()) { results.push(fullPath); } else if (entry.isSymbolicLink() followSymlinks) { // 符号链接指向目录时需要 stat 判断 const stat await fs.promises.stat(fullPath); if (stat.isDirectory()) { await visit(fullPath, depth 1); } else if (stat.isFile()) { results.push(fullPath); } } } } await visit(dir, 0); return results; }逻辑说明walk不负责匹配它只负责把目录里所有文件的绝对路径收集出来。visited集合用realpath记录这是防循环的关键。shouldIgnore在遍历入口就拦截比收集完再过滤省大量 IO。EACCES和EPERM直接跳过不让一个无权限目录毁掉整个搜索。参数说明maxDepth默认无限但实际使用建议给个值比如 10followSymlinks默认关闭因为符号链接极易制造循环shouldIgnore接收文件名和完整路径返回 true 表示跳过。3.2 匹配层字符串、正则、通配符三种条件怎么统一遍历拿到全部文件路径后进入匹配层。匹配层的设计决定工具对外好用不好用用户想按后缀找.log文件按完整文件名找一个确切文件按正则找一个模式。这三种条件要统一成一个接口。function createMatcher(pattern, options {}) { const { caseSensitive false } options; const fileName path.basename(filePath); if (pattern instanceof RegExp) { return (filePath) { const target caseSensitive ? fileName : fileName.toLowerCase(); const regex caseSensitive ? pattern : new RegExp(pattern.source, pattern.flags.replace(i, ) i); return regex.test(target); }; } if (typeof pattern string pattern.includes(*)) { // 通配符转正则 const escaped pattern .replace(/[.^${}()|[\]\\]/g, \\$) .replace(/\*/g, .*) .replace(/\?/g, .); const regex new RegExp(^${escaped}$, caseSensitive ? : i); return (filePath) regex.test(path.basename(filePath)); } // 纯字符串做个不区分大小写的包含判断 return (filePath) { const base path.basename(filePath); return caseSensitive ? base.includes(pattern) : base.toLowerCase().includes(pattern.toLowerCase()); }; }这段代码的核心是让三种输入形式收敛到同一个 “匹配函数” 上。字符串走includes包含匹配带星号走通配符转正则正则就直接用。所有匹配都作用在path.basename上也就是只匹配文件名不匹配路径避免路径里的目录名干扰结果。参数说明caseSensitive默认 false因为日常搜文件时大小写记混太常见了。通配符转正则需要做转义处理否则文件名里的.、会被当成正则元字符。转义的正则建议单独写个函数复用。3.3 忽略规则跳过 node_modules 和隐藏目录忽略规则是搜索工具和“能用”之间的一道分水岭。一个没有任何忽略的递归会把node_modules里几十万个文件全量读一遍几分钟都出不来结果。function defaultIgnore(name, fullPath) { // 点开头的隐藏目录和文件默认忽略 if (name.startsWith(.)) return true; // 最常见的重型目录 if (name node_modules || name bower_components) return true; return false; }默认忽略隐藏目录是个争议点我见过不少用户用ls的习惯但搜索工具默认忽略隐藏目录更符合直觉否则搜*.config会带出一堆编辑器配置文件。这个行为做成开关命令行里用--all打开。配合上一节的walk用法是walk(root, { shouldIgnore: defaultIgnore })。节点要在 enters 层面做拦截这样node_modules下面再深都不会被访问到IO 开销才能压住。3.4 参数设计与完整调用示例把前面的模块拼起来对外主函数应该是这样的它接收根目录、匹配条件、忽略规则返回匹配文件的绝对路径数组。async function fileSearch(rootDir, pattern, options {}) { const { maxDepth Infinity, followSymlinks false, shouldIgnore defaultIgnore, caseSensitive false, } options; const matcher createMatcher(pattern, { caseSensitive }); const allFiles await walk(rootDir, { maxDepth, followSymlinks, shouldIgnore }); return allFiles.filter((filePath) matcher(filePath)); }调用示例// 找出 src 目录下所有文件名里带 test 的 js 文件 const files await fileSearch(./src, test, { shouldIgnore: (name) name node_modules || name.startsWith(.), }); console.log(files);参数说明根目录支持相对路径函数内部建议path.resolve转成绝对路径再遍历模式参数支持字符串和正则两种类型。这个设计的好处是fileSearch本身可以被其他模块直接 import而 CLI 只是它的一层薄壳。4. 把搜索工具做成能交出去的 CLI参数解析、退出码与并发控制很多使用场景不在 Node 代码里而是在终端和脚本里。比如 CI 里检查某个配置文件是否存在这要求 js-filesearch 有一个好用的命令行界面并且能被脚本程序正确消费。4.1 手写参数解析不引第三方依赖的 parseArgsCLI 的参数解析不需要引入第三方库Node 自带的process.argv配合一个手写循环足够。关键在于处理选项和位置参数还要支持--分隔符来传递以-开头的搜索模式。const path require(path); function parseArgs(argv) { const options { root: process.cwd(), pattern: , ignore: [], maxDepth: Infinity, followSymlinks: false, caseSensitive: false, json: false, count: false, all: false, }; const positional []; let afterDoubleDash false; for (let i 0; i argv.length; i) { const arg argv[i]; if (afterDoubleDash) { positional.push(arg); continue; } if (arg --) { afterDoubleDash true; continue; } if (arg --json) { options.json true; } else if (arg --count) { options.count true; } else if (arg --all) { options.all true; } else if (arg --case-sensitive) { options.caseSensitive true; } else if (arg --follow-symlinks) { options.followSymlinks true; } else if (arg --max-depth) { options.maxDepth parseInt(argv[i], 10); } else if (arg --ignore) { options.ignore.push(argv[i]); } else if (arg.startsWith(-)) { console.error(未知参数: ${arg}); process.exit(2); } else { positional.push(arg); } } if (positional.length 1) options.root path.resolve(positional[0]); if (positional.length 2) options.pattern positional[1]; return options; }解析逻辑说明第一参数是根目录第二个是匹配模式和find的调用习惯保持一致。--ignore可以传多次每次收集一个目录名。--之后的所有参数都当作位置参数这样搜--foo开头的文件名时不会被解析成选项。参数说明根目录默认当前工作目录避免用户漏传时直接报错模式是必备参数如果缺失就用console.error给出错误提示后退出这是 CLI 的基本素养。4.2 输出格式与退出码让脚本能消费结果CLI 的输出设计直接决定脚本好不好用。我见过不少工具只在控制台打印文件名脚本里没法拿结构化的结果这是最常见的设计缺陷。js-filesearch 应当提供三种输出模式默认每行一个路径、--json输出数组、--count只输出数量。async function main() { const options parseArgs(process.argv.slice(2)); if (!options.pattern) { console.error(请提供搜索模式例如: js-filesearch ./src *.test.js); process.exit(2); } const ignoreRules (name) { if (!options.all (name.startsWith(.) || name node_modules)) return true; return options.ignore.includes(name); }; const files await fileSearch(options.root, options.pattern, { maxDepth: options.maxDepth, followSymlinks: options.followSymlinks, caseSensitive: options.caseSensitive, shouldIgnore: ignoreRules, }); if (options.count) { console.log(files.length); process.exit(files.length 0 ? 0 : 1); } if (options.json) { console.log(JSON.stringify(files, null, 2)); } else { files.forEach((f) console.log(f)); } process.exit(files.length 0 ? 0 : 1); } main().catch((err) { console.error(err.message); process.exit(1); });退出码约定很重要找到文件返回 0没有找到返回 1参数错误返回 2程序异常返回 1。这套约定和 grep 的退出码保持一致CI 脚本里判断“这个文件是否存在于项目里”时可以直接写if js-filesearch ./src config.prod.js; then ...不需要解析输出文本。4.3 并发遍历限制同时打开的目录句柄早期我做的第一版递归会把几千个目录的readdir同时铺出去在机械硬盘或冷缓存条件下直接拖慢整机。后来加了一个简单的并发控制器最多同时跑有限个目录遍历任务其余排队。async function workerPool(tasks, concurrency, worker) { const results new Array(tasks.length); let nextIndex 0; async function runWorker() { while (nextIndex tasks.length) { const index nextIndex; results[index] await worker(tasks[index], index); } } const workers Array.from({ length: concurrency }, runWorker); await Promise.all(workers); return results; }逻辑说明workerPool是一个通用并发控制函数tasks是所有目录路径concurrency是同时进行的遍历任务数。每个 worker 从共享的nextIndex取任务处理完再取下一个直到全部完成。这样既控制了并发又不浪费空闲的 worker。参数说明并发数一般设置在 16 到 32 之间比较合适过小发挥不了多核优势过大反而造成磁盘 IO 争抢。测试时可以用--concurrency可配置生产使用固定一个相对保守的值。5. 文件搜索的 5 个高频坑从事件循环阻塞到路径大小写这一章直接给结论每条都是实际跑过、后来花时间定位过的真实问题。按“现象 → 原因 → 解决”的顺序写方便排查时对照。5.1 搜索时整个进程卡死其他请求全部超时现象在 Web 服务里调用搜索逻辑搜索期间其他接口全部无响应CPU 飙高。原因第一版用了fs.readdirSync同步递归遍历期间事件循环被完全阻塞。Node 的单线程模型下同步 IO 会卡住所有异步回调包括 HTTP 请求的处理。解决把同步调用全部替换成fs.promises异步版本配合workerPool控制并发。如果搜索的目录特别大更彻底的做法是放到worker_threads里跑主线程只接收返回结果。5.2 Windows 上路径分隔符导致正则匹配不到文件现象同一套代码在 macOS 上匹配正常放到 Windows 上报出EISDIR错误或者结果为空调试发现路径变成了C:\src\test.js反斜杠把正则的转义序列搅乱了。原因path.join在 Windows 上返回反斜杠分隔的路径而正则里的\t、\s会被当成制表符或空白字符直接改变匹配语义。解决在所有进入匹配环节的路径上统一做一次规范化把反斜杠替换成正斜杠。实现很简单filePath.split(path.sep).join(/)或者用path.posix.normalize统一格式后再交给匹配层。5.3 结果集爆炸搜完node_modules内存占用几个 GB现象搜索整个项目目录结果返回了十几万条路径控制台刷屏内存占用暴涨。原因忽略规则没生效。通常是shouldIgnore的匹配粒度不对只匹配了绝对路径的结尾没有拦截node_modules下更深层的所有子目录导致遍历仍然下钻了。解决忽略规则必须面向每个 entry 的name和fullPath做检查只要当前目录名是node_modules整个子树就都不该进。检查这个问题的办法是在walk里加一个console.debug传参观察忽略规则被调用的频率正常搜src目录时node_modules下的条目不该出现。5.4 symlink 循环让搜索永远跑不完现象搜索包含软链接的目录时进程卡住CPU 满载很久没有输出最后堆栈溢出报错。原因一个符号链接指向它的父目录或某个祖先目录递归遍历时会在环里打转。第一版没有记录访问过的realpath结果无限循环。解决walk里加visited集合每次进入目录前先realpath再查重命中就跳过。另外默认关闭followSymlinks让用户在明确需要跟随链接时才打开。打开时务必保留visited机制不能依赖用户自觉。5.5 搜中文文件名和带特殊字符的文件名结果为空现象用户搜索包含中文的文件名如搜测试或会议纪要或者搜带[]、的文件名结果明明有文件却搜不到。原因规则转成正则时没有转义特殊字符[被当作字符组开始被当作量词中文匹配问题则出在大小写转换上某些 locale 下toLowerCase行为不一致。解决纯字符串匹配不要走正则直接用字符串includes。通配符转正则时先把所有正则元字符批量转义。中文匹配只要保证不区分大小写时用的是原文件名字符串不做其他变换即可。6. 让 js-filesearch 真正经用读 .gitignore、修改时间排序和编辑器集成当基础搜索功能稳定之后真正让工具提升一个档次的不是搜索本身而是它融入工作流的能力。这里讲三个值得做的小功能按投入产出比排序。6.1 让忽略规则读取 .gitignore硬编码的node_modules忽略规则只能覆盖最通用的情况真实项目的忽略需求都在.gitignore里。常见做法是解析.gitignore文件把里面的规则变成shouldIgnore的一部分。不需要完全实现 git 的复杂语义只要支持最基本的目录名/、*.ext和注释行就够了解析逻辑不到 50 行。function parseGitignore(content) { const rules []; content.split(\n).forEach((line) { const trimmed line.trim(); if (!trimmed || trimmed.startsWith(#)) return; if (trimmed.endsWith(/)) { rules.push({ type: dir, name: trimmed.slice(0, -1) }); } else if (trimmed.startsWith(*.)) { rules.push({ type: ext, ext: trimmed.slice(2) }); } }); return rules; }这个简单版的.gitignore解析器覆盖了 80% 的常见规则。把它接到shouldIgnore里搜索时就不会把dist、.cache这类构建产物带出来。6.2 给搜索结果加上修改时间排序搜索一个文件你通常想找的是“最近动过的那个”而不是“名字排在最前面的那个”。给fileSearch增加一个sortBy: mtime的选项在返回结果前对每个文件做一次fs.stat拿修改时间按时间倒序排。async function sortByMtime(files) { const withTime await Promise.all(files.map(async (f) { const stat await fs.promises.stat(f); return { f, mtime: stat.mtimeMs }; })); return withTime.sort((a, b) b.mtime - a.mtime).map((x) x.f); }注意这会额外增加一次stat的开销所以只建议在结果集小于几百条的时候用否则先按名字过滤出候选集再对候选集排序。6.3 集成到编辑器任务和文件管理器最后一个让工具落地的用法把编译好的命令行脚本放到全局 PATH 里然后在编辑器里定义一个快速文件搜索任务绑一个快捷键直接调用把输出接到 QuickPick 列表。在 Visual Studio Code 里就是tasks.json里配一个shell任务;在命令行里则可以配合fzf这类模糊查找交互工具把文件搜索的输出输入给交互选择器。这套组合让“搜文件”变成一个真正的日常操作敲几个字母选一下就跳转比在文件树里逐层翻目录高效得多。说到底文件搜索这个方向没有太高深的技术能不能做得顺手全看细节。我踩过的所有坑里最深刻的教训是搜文件的工具最怕的不是搜不到而是把用户机器拖死。所有功能设计都应该先问一句“这个操作在最坏情况下要面对多少文件”。把忽略规则、并发控制、深度限制做好工具就赢了一半把输出格式和退出码做对脚本就能基于它做更多事情。希望这篇笔记里的方案和避坑记录能帮你少走几轮弯路希望帮到你。本文还有配套的精品资源点击获取