Node.js 使用 fs.readdir 遍历目录结构

一、Node.js 文件系统模块（fs）概述

在Node.js的生态系统中，文件系统模块（fs）是极为重要的一部分，它提供了一系列用于与文件系统进行交互的API。无论是读取文件内容、写入文件数据，还是对目录进行操作，fs模块都能派上用场。而fs.readdir函数则是其中专门用于读取目录内容的方法，通过它我们能够遍历目录结构，获取目录下的文件和子目录信息。

Node.js中的fs模块有两种使用模式：同步模式和异步模式。同步模式下的操作会阻塞Node.js的事件循环，直到操作完成，这在处理大量I/O操作或需要快速响应的应用场景中可能不是最佳选择。而异步模式则不会阻塞事件循环，允许Node.js继续执行其他任务，等I/O操作完成后通过回调函数或Promise来处理结果。fs.readdir同样有同步（fs.readdirSync）和异步（fs.readdir）两个版本，在实际应用中，异步版本由于其非阻塞特性，使用更为广泛。

二、fs.readdir 基础用法

（一）异步版本：fs.readdir

fs.readdir的基本语法如下：

const fs = require('fs');
const path = require('path');

fs.readdir('/path/to/directory', (err, files) => {
    if (err) {
        console.error('Error reading directory:', err);
        return;
    }
    console.log('Files in the directory:', files);
});

在上述代码中：

首先通过require引入了fs模块，这是使用文件系统相关功能的前提。同时引入path模块，虽然在这个简单示例中暂未用到，但在处理路径相关操作时path模块非常有用，比如拼接路径、解析路径等。
fs.readdir接受两个参数，第一个参数是要读取的目录路径，这里是/path/to/directory，你需要将其替换为真实存在的目录路径。第二个参数是一个回调函数，当读取目录操作完成后，该回调函数会被调用。
在回调函数中，err参数用于接收可能发生的错误。如果读取目录过程中出现问题，比如目录不存在、没有权限访问等，err会包含错误信息。我们通过console.error打印错误信息，并使用return语句提前结束函数执行。
如果读取操作成功，files参数会是一个数组，包含了目录下的文件名和子目录名（不包含路径）。我们通过console.log将这些信息打印出来。

（二）同步版本：fs.readdirSync

fs.readdirSync的用法相对简单直接，因为它不需要通过回调函数来处理结果。其语法如下：

const fs = require('fs');
const path = require('path');

try {
    const files = fs.readdirSync('/path/to/directory');
    console.log('Files in the directory:', files);
} catch (err) {
    console.error('Error reading directory:', err);
}

在这段代码中：

同样引入了fs和path模块。
使用fs.readdirSync读取目录，它只接受一个参数，即要读取的目录路径。如果操作成功，它会直接返回包含目录下文件名和子目录名的数组。
由于同步操作可能会抛出异常，我们使用try...catch块来捕获可能发生的错误。如果发生错误，catch块中的代码会执行，打印错误信息。

三、深入理解fs.readdir

（一）编码选项

fs.readdir还可以接受第三个参数，用于指定文件名的编码。默认情况下，它使用'utf8'编码。如果你处理的文件名包含特殊字符或非UTF - 8编码的字符，可能需要指定其他编码。例如，要使用'buffer'编码，可以这样写：

const fs = require('fs');
const path = require('path');

fs.readdir('/path/to/directory', 'buffer', (err, files) => {
    if (err) {
        console.error('Error reading directory:', err);
        return;
    }
    console.log('Files in the directory:', files);
});

当使用'buffer'编码时，files数组中的文件名会以Buffer对象的形式返回。这在处理一些需要以字节形式操作文件名的场景中非常有用，比如处理二进制文件或特定编码格式的文件时。

（二）遍历子目录

单纯使用fs.readdir只能读取指定目录下的直接内容，要遍历整个目录结构（包括子目录及其子目录等），我们需要递归调用fs.readdir。以下是一个简单的递归遍历目录结构的示例：

const fs = require('fs');
const path = require('path');

function traverseDirectory(dirPath) {
    try {
        const files = fs.readdirSync(dirPath);
        files.forEach(file => {
            const filePath = path.join(dirPath, file);
            const stats = fs.statSync(filePath);
            if (stats.isDirectory()) {
                console.log('Directory:', filePath);
                traverseDirectory(filePath);
            } else {
                console.log('File:', filePath);
            }
        });
    } catch (err) {
        console.error('Error reading directory:', err);
    }
}

// 调用函数开始遍历
traverseDirectory('/path/to/root/directory');

在这个示例中：

定义了一个traverseDirectory函数，它接受一个目录路径作为参数。
在函数内部，首先使用fs.readdirSync读取目录内容。由于这里采用同步操作，在遍历大目录时可能会有性能问题，但为了代码逻辑简洁先采用这种方式。实际应用中可以使用异步方式并结合async/await来优化。
使用forEach遍历读取到的文件和目录名。通过path.join将目录路径和文件名拼接成完整的文件或目录路径。
使用fs.statSync获取文件或目录的状态信息。通过stats.isDirectory()判断当前路径是目录还是文件。如果是目录，打印目录路径并递归调用traverseDirectory函数继续遍历该子目录；如果是文件，则直接打印文件路径。
最后通过调用traverseDirectory('/path/to/root/directory')来启动整个目录结构的遍历，你需要将/path/to/root/directory替换为实际要遍历的根目录路径。

（三）异步递归遍历

为了避免同步操作带来的阻塞问题，我们可以将上述同步递归遍历改写成异步版本，结合async/await和Promise来实现：

const fs = require('fs').promises;
const path = require('path');

async function traverseDirectoryAsync(dirPath) {
    try {
        const files = await fs.readdir(dirPath);
        for (const file of files) {
            const filePath = path.join(dirPath, file);
            const stats = await fs.stat(filePath);
            if (stats.isDirectory()) {
                console.log('Directory:', filePath);
                await traverseDirectoryAsync(filePath);
            } else {
                console.log('File:', filePath);
            }
        }
    } catch (err) {
        console.error('Error reading directory:', err);
    }
}

// 调用函数开始遍历
traverseDirectoryAsync('/path/to/root/directory');

在这个异步版本中：

通过require('fs').promises获取fs模块的Promise版本，这样fs.readdir和fs.stat等方法会返回Promise对象。
traverseDirectoryAsync函数被定义为async函数，这允许我们在函数内部使用await关键字。
使用await fs.readdir(dirPath)异步读取目录内容，等待Promise解决后获取文件和目录名数组。
使用for...of循环遍历数组，同样使用await fs.stat(filePath)异步获取文件或目录的状态信息。
根据是否为目录进行相应处理，递归调用traverseDirectoryAsync函数时也使用await确保子目录遍历完成后再继续执行后续操作。

四、处理文件和目录的更多操作

（一）过滤文件类型

在遍历目录结构时，我们常常需要过滤出特定类型的文件。例如，只获取所有的JavaScript文件（.js）。以下是在异步递归遍历中添加文件类型过滤的示例：

const fs = require('fs').promises;
const path = require('path');

async function traverseDirectoryAsyncAndFilter(dirPath, fileExtension) {
    try {
        const files = await fs.readdir(dirPath);
        for (const file of files) {
            const filePath = path.join(dirPath, file);
            const stats = await fs.stat(filePath);
            if (stats.isDirectory()) {
                await traverseDirectoryAsyncAndFilter(filePath, fileExtension);
            } else if (path.extname(file) === fileExtension) {
                console.log('Matched File:', filePath);
            }
        }
    } catch (err) {
        console.error('Error reading directory:', err);
    }
}

// 调用函数开始遍历并过滤.js文件
traverseDirectoryAsyncAndFilter('/path/to/root/directory', '.js');

在这个示例中：

traverseDirectoryAsyncAndFilter函数除了接受目录路径dirPath外，还接受一个文件扩展名fileExtension作为参数。
在处理文件时，通过path.extname(file)获取文件的扩展名，并与fileExtension进行比较。如果扩展名匹配，则打印该文件路径。

（二）对文件和目录执行操作

除了读取和过滤，我们还可以对遍历到的文件和目录执行各种操作。例如，复制文件、删除文件或目录等。以下是一个在遍历目录结构时删除所有空目录的示例：

const fs = require('fs').promises;
const path = require('path');

async function removeEmptyDirectories(dirPath) {
    try {
        const files = await fs.readdir(dirPath);
        if (files.length === 0) {
            await fs.rmdir(dirPath);
            console.log('Removed empty directory:', dirPath);
        } else {
            for (const file of files) {
                const filePath = path.join(dirPath, file);
                const stats = await fs.stat(filePath);
                if (stats.isDirectory()) {
                    await removeEmptyDirectories(filePath);
                }
            }
            const updatedFiles = await fs.readdir(dirPath);
            if (updatedFiles.length === 0) {
                await fs.rmdir(dirPath);
                console.log('Removed empty directory:', dirPath);
            }
        }
    } catch (err) {
        console.error('Error reading or removing directory:', err);
    }
}

// 调用函数开始删除空目录
removeEmptyDirectories('/path/to/root/directory');

在这个示例中：

removeEmptyDirectories函数接受一个目录路径作为参数。
首先读取目录内容，如果目录为空（files.length === 0），则使用fs.rmdir删除该目录，并打印提示信息。
如果目录不为空，遍历目录中的子项。如果子项是目录，则递归调用removeEmptyDirectories函数处理子目录。
递归处理完子目录后，再次读取目录内容，检查目录是否变为空。如果变为空，则删除该目录。

五、性能优化与注意事项

（一）性能优化

异步操作优先：在处理大规模目录结构遍历或I/O密集型任务时，使用异步版本的fs.readdir及相关文件系统操作可以显著提高性能，避免阻塞事件循环。
减少同步操作：如前面示例中所示，同步操作虽然代码逻辑简单，但在处理大目录时会导致Node.js应用暂停，直到操作完成。应尽量将同步操作转换为异步操作，结合async/await或Promise来管理异步流程。
批量处理：在进行文件或目录操作时，如果可以，尽量批量处理而不是逐个处理。例如，在删除多个文件时，可以先收集要删除的文件路径，然后使用Promise.all批量执行删除操作，这样可以减少I/O操作的次数，提高效率。

（二）注意事项

权限问题：确保Node.js应用具有足够的权限来读取、写入或删除指定目录及其内容。在不同操作系统下，权限管理方式有所不同。例如，在Linux或macOS系统中，需要注意文件和目录的所有者、组以及权限位（rwx）；在Windows系统中，需要注意用户账户控制（UAC）等权限设置。
路径处理：使用path模块来处理路径是非常重要的，因为不同操作系统的路径分隔符不同（Windows使用\，Linux和macOS使用/）。path.join、path.resolve等方法可以确保路径在不同操作系统下都能正确拼接和解析。
错误处理：在文件系统操作中，错误处理至关重要。无论是异步还是同步操作，都可能因为各种原因失败，如文件不存在、磁盘空间不足等。务必使用适当的错误处理机制，如在异步操作的回调函数中处理错误，或在同步操作中使用try...catch块捕获异常。

六、与其他模块结合使用

（一）与`path`模块结合

path模块在处理目录结构遍历中起着关键作用。除了前面示例中使用的path.join方法用于拼接路径外，path.parse方法可以解析路径，返回一个包含目录名、文件名、扩展名等信息的对象。例如：

const path = require('path');

const filePath = '/home/user/documents/file.txt';
const parsedPath = path.parse(filePath);
console.log('Directory:', parsedPath.dir);
console.log('Filename:', parsedPath.name);
console.log('Extension:', parsedPath.ext);

在遍历目录结构时，path.parse可以帮助我们更好地分析文件路径，提取有用信息，以便进行更复杂的操作，比如根据文件名或扩展名进行分类处理等。

（二）与`stream`模块结合

在处理大量文件或大文件时，stream模块可以提高性能和内存使用效率。例如，当我们需要读取遍历到的文件内容时，可以使用可读流（fs.createReadStream）。以下是一个简单示例，在遍历目录结构时读取所有文本文件内容：

const fs = require('fs').promises;
const path = require('path');
const { createReadStream } = require('fs');

async function readTextFilesInDirectory(dirPath) {
    try {
        const files = await fs.readdir(dirPath);
        for (const file of files) {
            const filePath = path.join(dirPath, file);
            const stats = await fs.stat(filePath);
            if (stats.isDirectory()) {
                await readTextFilesInDirectory(filePath);
            } else if (path.extname(file) === '.txt') {
                const readableStream = createReadStream(filePath, 'utf8');
                readableStream.on('data', (chunk) => {
                    console.log('Read from file:', chunk);
                });
                readableStream.on('end', () => {
                    console.log('Finished reading file.');
                });
            }
        }
    } catch (err) {
        console.error('Error reading directory:', err);
    }
}

// 调用函数开始读取文本文件
readTextFilesInDirectory('/path/to/root/directory');

在这个示例中，对于找到的文本文件，通过createReadStream创建可读流，并监听data事件来逐块读取文件内容，监听end事件来得知文件读取完成。这样可以避免一次性将整个大文件读入内存，提高内存使用效率。

（三）与`util`模块结合

util模块提供了一些实用工具，其中util.promisify可以将基于回调的函数转换为返回Promise的函数。在Node.js早期版本中，fs模块的一些方法只有基于回调的形式，使用util.promisify可以方便地将它们转换为Promise形式，以便更好地与async/await配合使用。例如：

const fs = require('fs');
const util = require('util');
const path = require('path');

const readdir = util.promisify(fs.readdir);
const stat = util.promisify(fs.stat);

async function traverseDirectoryWithPromisify(dirPath) {
    try {
        const files = await readdir(dirPath);
        for (const file of files) {
            const filePath = path.join(dirPath, file);
            const stats = await stat(filePath);
            if (stats.isDirectory()) {
                console.log('Directory:', filePath);
                await traverseDirectoryWithPromisify(filePath);
            } else {
                console.log('File:', filePath);
            }
        }
    } catch (err) {
        console.error('Error reading directory:', err);
    }
}

// 调用函数开始遍历
traverseDirectoryWithPromisify('/path/to/root/directory');

在这个示例中，通过util.promisify将fs.readdir和fs.stat转换为返回Promise的函数，然后在async函数中使用await进行异步操作，使得代码逻辑更加清晰，与现代的异步编程风格相契合。

七、在实际项目中的应用场景

（一）静态资源管理

在Web开发中，经常需要管理静态资源，如HTML、CSS、JavaScript文件以及图片等。通过遍历项目的静态资源目录结构，可以实现资源的压缩、合并、版本控制等操作。例如，使用工具对CSS和JavaScript文件进行压缩，然后将压缩后的文件替换原文件，或者为静态资源文件名添加版本号以实现缓存控制。

const fs = require('fs').promises;
const path = require('path');
const cssmin = require('cssmin');
const terser = require('terser');

async function optimizeStaticResources(dirPath) {
    try {
        const files = await fs.readdir(dirPath);
        for (const file of files) {
            const filePath = path.join(dirPath, file);
            const stats = await fs.stat(filePath);
            if (stats.isDirectory()) {
                await optimizeStaticResources(filePath);
            } else if (path.extname(file) === '.css') {
                const cssContent = await fs.readFile(filePath, 'utf8');
                const minifiedCss = cssmin(cssContent);
                await fs.writeFile(filePath, minifiedCss);
                console.log('Optimized CSS file:', filePath);
            } else if (path.extname(file) === '.js') {
                const jsContent = await fs.readFile(filePath, 'utf8');
                const { code } = await terser.minify(jsContent);
                await fs.writeFile(filePath, code);
                console.log('Optimized JavaScript file:', filePath);
            }
        }
    } catch (err) {
        console.error('Error optimizing static resources:', err);
    }
}

// 调用函数开始优化静态资源
optimizeStaticResources('/path/to/static/resources');

在这个示例中，遍历静态资源目录，对CSS文件使用cssmin进行压缩，对JavaScript文件使用terser进行压缩，并将压缩后的内容写回原文件。

（二）文件索引与搜索

在文档管理系统或搜索引擎应用中，需要对文件内容进行索引，以便快速搜索。通过遍历文件目录结构，获取文件路径和元数据（如文件名、文件大小、修改时间等），并将这些信息存储到数据库或索引文件中。例如，可以使用sqlite3数据库来存储文件索引信息。

const fs = require('fs').promises;
const path = require('path');
const sqlite3 = require('sqlite3').verbose();

async function indexFiles(dirPath) {
    return new Promise((resolve, reject) => {
        const db = new sqlite3.Database('file_index.db', (err) => {
            if (err) {
                reject(err);
            } else {
                db.run(`CREATE TABLE IF NOT EXISTS files (
                    id INTEGER PRIMARY KEY AUTOINCREMENT,
                    path TEXT UNIQUE,
                    name TEXT,
                    size INTEGER,
                    modified_time TEXT
                )`);
                (async () => {
                    try {
                        const files = await fs.readdir(dirPath);
                        for (const file of files) {
                            const filePath = path.join(dirPath, file);
                            const stats = await fs.stat(filePath);
                            if (stats.isDirectory()) {
                                await indexFiles(filePath);
                            } else {
                                db.run(`INSERT OR IGNORE INTO files (path, name, size, modified_time) VALUES (?,?,?,?)`,
                                    filePath,
                                    file,
                                    stats.size,
                                    stats.mtime.toISOString(),
                                    (err) => {
                                        if (err) {
                                            console.error('Error inserting file into database:', err);
                                        }
                                    });
                            }
                        }
                        db.close();
                        resolve();
                    } catch (err) {
                        reject(err);
                    }
                })();
            }
        });
    });
}

// 调用函数开始索引文件
indexFiles('/path/to/files/directory').then(() => {
    console.log('Files indexed successfully.');
}).catch((err) => {
    console.error('Error indexing files:', err);
});

在这个示例中，遍历文件目录结构，将文件的路径、名称、大小和修改时间等信息插入到SQLite数据库的files表中。这样就可以通过查询数据库来实现文件的搜索功能。

（三）备份与恢复

在数据管理中，备份和恢复是重要的操作。通过遍历源目录结构，将文件复制到备份目录，可以实现数据备份。在恢复时，反向操作即可。以下是一个简单的备份目录结构的示例：

const fs = require('fs').promises;
const path = require('path');
const { createReadStream, createWriteStream } = require('fs');

async function backupDirectory(sourceDir, targetDir) {
    try {
        const files = await fs.readdir(sourceDir);
        for (const file of files) {
            const sourceFilePath = path.join(sourceDir, file);
            const targetFilePath = path.join(targetDir, file);
            const stats = await fs.stat(sourceFilePath);
            if (stats.isDirectory()) {
                await fs.mkdir(targetFilePath);
                await backupDirectory(sourceFilePath, targetFilePath);
            } else {
                const readableStream = createReadStream(sourceFilePath);
                const writableStream = createWriteStream(targetFilePath);
                readableStream.pipe(writableStream);
                readableStream.on('end', () => {
                    console.log('Copied file:', sourceFilePath);
                });
            }
        }
    } catch (err) {
        console.error('Error backing up directory:', err);
    }
}

// 调用函数开始备份
backupDirectory('/path/to/source/directory', '/path/to/backup/directory');

在这个示例中，遍历源目录，对于子目录，在目标备份目录中创建相应的子目录；对于文件，通过可读流和可写流将文件内容从源文件复制到目标文件，从而实现整个目录结构的备份。

通过以上对fs.readdir在Node.js中遍历目录结构的详细介绍，包括基础用法、深入理解、性能优化、与其他模块结合以及实际应用场景等方面，相信你已经对如何在Node.js项目中有效地使用fs.readdir来处理目录结构有了全面的认识。在实际开发中，可以根据具体需求灵活运用这些知识，实现高效、可靠的文件系统操作。

Node.js 使用 fs.readdir 遍历目录结构

一、Node.js 文件系统模块（fs）概述

二、fs.readdir 基础用法

（一）异步版本：fs.readdir

（二）同步版本：fs.readdirSync

三、深入理解fs.readdir

（一）编码选项

（二）遍历子目录

（三）异步递归遍历

四、处理文件和目录的更多操作

（一）过滤文件类型

（二）对文件和目录执行操作

五、性能优化与注意事项

（一）性能优化

（二）注意事项

六、与其他模块结合使用

（一）与path模块结合

（二）与stream模块结合

（三）与util模块结合

七、在实际项目中的应用场景

（一）静态资源管理

（二）文件索引与搜索

（三）备份与恢复

（一）与`path`模块结合

（二）与`stream`模块结合

（三）与`util`模块结合