# readdirp 中文文档

规范地址：https://npmcn.com/package/readdirp/

版本：5\.1\.1
npm 元数据更新时间：2026-08-06T06:26:39.304Z
中文译文更新时间：2026-11-04T14:24:11.995Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/readdirp
原文对照：https://npmcn.com/package/readdirp/?lang=original
项目主页：https://github.com/paulmillr/readdirp
源码仓库：https://github.com/paulmillr/readdirp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：26.8 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>= 20\.19\.0
- 运行依赖：0 个
- 首次发布：2012-07-18T11:44:10.802Z
- 最新版本发布：2026-08-06T06:26:38.975Z
- 近 30 天下载量：826608616（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 2 个）

## 中文简介

fs的递归版本。readdir具有较小的RAM和CPU占用

## 安装

```sh
npm install readdirp
```

也可以使用：`pnpm add readdirp`、`yarn add readdirp`、`bun add readdirp`

## README

# readdirp [![Weekly downloads](https://img.shields.io/npm/dw/readdirp.svg)](https://github.com/paulmillr/readdirp)

fs.readdir的递归版本。公开了一个 **流API** （RAM和CPU占用空间小）和一个 **承诺API**。

比内置更快 `fs.readdir recursive: true`，并且使用更少的RAM。

```sh
npm install readdirp
jsr add jsr:@paulmillr/readdirp
```

```javascript
// Use streams to achieve small RAM & CPU footprint.
// 1) Streams example with for-await.
import readdirp from 'readdirp';
for await (const entry of readdirp('.')) {
  const {path} = entry;
  console.log(`${JSON.stringify({path})}`);
}

// 2) Streams example, non for-await.
// Print out all JS files along with their size within the current folder & subfolders.
import readdirp from 'readdirp';
readdirp('.', {alwaysStat: true, fileFilter: (f) => f.basename.endsWith('.js')})
  .on('data', (entry) => {
    const {path, stats: {size}} = entry;
    console.log(`${JSON.stringify({path, size})}`);
  })
  // Optionally call stream.destroy() in `warn()` in order to abort and cause 'close' to be emitted
  .on('warn', error => console.error('non-fatal error', error))
  .on('error', error => console.error('fatal error', error))
  .on('end', () => console.log('done'));

// 3) Promise example. More RAM and CPU than streams / for-await.
import { readdirpPromise } from 'readdirp';
const files = await readdirpPromise('.');
console.log(files.map(file => file.path));

// Other options.
import readdirp from 'readdirp';
readdirp('test', {
  fileFilter: (f) => f.basename.endsWith('.js'),
  directoryFilter: (d) => d.basename !== '.git',
  // directoryFilter: (di) => di.basename.length === 9
  type: 'files_directories',
  depth: 1
});
```

## API

`const stream = readdirp(root[, options])` - - - - - - **流API**

-   递归读取给定的根并返回 `stream` 的 [输入信息](https://npmcn.com/package/readdirp/#readme-entryinfo)
-   可选地使用如下 `for await (const entry of stream)` 使用node.js 10+ (`asyncIterator`）.
-   `on('data', (entry) => {})` [输入信息](https://npmcn.com/package/readdirp/#readme-entryinfo) 对于每个文件/ dir。
-   `on('warn', (error) => {})` 非致命的 `Error` 这样可以防止文件/ dir被处理。示例：用户无法访问。
-   `on('error', (error) => {})` 致命的 `Error` 这也是流的终点。例如：传入的非法选项。
-   `on('end')` -我们做完了。当找到所有条目并且不再发出更多条目时调用。
-   `on('close')` -流被破坏通过 `stream.destroy()`。 如果您想在非致命错误时手动中止，可能会很有用。 在这一点上，流不再 `readable` 并且不会发出更多的条目、警告或错误
-   要了解有关流的更多信息，请参阅非常详细的 [Nodejs流文档](https://nodejs.org/api/stream.html) 或者是 [stream-handbook](https://github.com/substack/stream-handbook)

`const entries = await readdirp.promise(root[, options])` - - - - - - **承诺API**。返回的列表 [输入信息](https://npmcn.com/package/readdirp/#readme-entryinfo)。

第一个参数总是 `root`，开始读取并递归到子目录的路径。

### 选项

-   `fileFilter`：过滤包括或排除文件
    -   **函数**：该函数接受一个条目info作为参数，并返回true以包含该条目，返回false以排除该条目
-   `directoryFilter`：过滤器包括/排除找到的目录和递归目录。未通过筛选器的目录将不会被递归到。
-   `depth: 5`：深度，即使找到更多的子目录，也要停止递归
-   `type: 'files'`确定流上的数据事件是否应该为 `'files'` (默认), `'directories'`， `'files_directories'`,或 `'all'`。设置为 `'all'` 还将包括其他类型的文件描述符的条目，如字符设备、Unix套接字和命名管道。
-   `alwaysStat: false`：总是返回 `stats` 属性设置每个文件。默认是 `false`， readdirp将返回 `Dirent` 条目。将其设置为 `true` 可以双读目录执行时间-使用它只有当你需要文件 `size`， `mtime` 等。不能在<10.10.0的节点上启用。
-   `lstat: false`：在流中包括符号链接条目和文件。当 `true`， `fs.lstat` 用Would代替 `fs.stat`

### `EntryInfo`

具有以下属性：

-   `path: 'assets/javascripts/react.js'`：文件/目录的路径（相对于给定的根目录）
-   `fullPath: '/Users/dev/projects/app/assets/javascripts/react.js'`：找到的文件/目录的完整路径
-   `basename: 'react.js'`：文件/目录名
-   `dirent: fs.Dirent`:内置 [目录条目对象](https://nodejs.org/api/fs.html#fs_class_fs_dirent) -只与 `alwaysStat: false`
-   `stats: fs.Stats`：内置的 [统计对象](https://nodejs.org/api/fs.html#fs_class_fs_stats) -只与 `alwaysStat: true`

## 更新日志

-   4.0（2024年8月25日）用typescript重写，生成common.js / esm混合模块。
    -   删除glob支持和所有依赖项
    -   确保你在使用 `let {readdirp} = require('readdirp')` 在common.js
-   3.5（2020年10月13日）禁止基于目录的递归符号链接。 之前，它可能会进入无限循环。
-   3.4（2020年3月19日）增加了对基于目录的符号链接的支持。
-   3.3（2019年12月6日）稳定RAM消耗并实现性能管理 `highWaterMark` 选择。修复了相关的竞争条件 `for-await` 循环。
-   3.2（2019年10月14日）将性能提高了250%，并使流实现更加习惯化。
-   3.1（2019年7月7日）带来 `bigint` 支持 `stat` 输出。这在某些情况下是向后不兼容的。小心些而已。如果使用不当，就会看到“TypeError：不能混合使用BigInt和其他类型，请使用显式转换”。
-   3.0带来了巨大的性能改进和流反压支持。
-   升级2。X到3.x：
    -   签名更改为 `readdirp(options)` 来 `readdirp(root, options)`
    -   用承诺API替换回调API。
    -   重命名 `entryType` 选项 `type`
    -   重命名 `entryType: 'both'` 来 `'files_directories'`
    -   `EntryInfo`
        -   重命名 `stat` 来 `stats`
            -   仅当 `alwaysStat: true`
            -   `dirent` 发出，而不是 `stats` 默认为 `alwaysStat: false`
        -   重命名 `name` 来 `basename`
        -   删除 `parentDir` 和 `fullParentDir` 属性
-   支持的node.js版本：
    -   4.X：节点14+
    -   3.X：节点8+
    -   2.X：节点0.6+

## 许可证

版权所有：托斯滕·洛伦兹，保罗·米勒[https://paulmillr.com](https://paulmillr.com/)）

MIT许可证，见 [许可证](https://npmcn.com/package/readdirp/LICENSE) 文件。

## 常见问题

### readdirp 是什么？

fs的递归版本。readdir具有较小的RAM和CPU占用

### 如何安装 readdirp？

在项目目录运行 npm install readdirp，或使用 pnpm add / yarn add / bun add。

### readdirp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### readdirp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### readdirp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### readdirp 可以商用吗？

readdirp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### readdirp 的下载量有多少？

根据 npm 官方下载统计，readdirp 在 2026/10/05 – 2026/11/03 这 30 天内被下载 826,608,616 次，日均约 27,553,621 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### readdirp 还在维护吗？

最新版本 5\.1\.1 发布于 2026/08/06（2 个月前）；至今共发布 48 个版本，其中过去 12 个月发布了 2 个；首次发布于 2012/07/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。