# @folder/readdir 中文文档

规范地址：https://npmcn.com/package/%40folder/readdir/

版本：3\.1\.0
npm 元数据更新时间：2022-04-05T11:35:52.449Z
中文译文更新时间：2026-11-15T04:07:39.210Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：30.3 kB，7 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=10
- 运行依赖：0 个
- 首次发布：2019-04-22T15:19:36.465Z
- 最新版本发布：2021-05-12T17:43:07.391Z
- 近 30 天下载量：3871（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 0 个）

## 中文简介

递相读取一目录,快活快活.

## 安装

```sh
npm install @folder/readdir
```

也可以使用：`pnpm add @folder/readdir`、`yarn add @folder/readdir`、`bun add @folder/readdir`

## README

# @ 文件夹/ 已读目录 [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://paypal.me/jonathanschlinkert?locale.x=en_US) [![NPM version](https://img.shields.io/npm/v/@folder/readdir.svg?style=flat)](https://www.npmjs.com/package/@folder/readdir) [![NPM monthly downloads](https://img.shields.io/npm/dm/@folder/readdir.svg?style=flat)](https://npmjs.org/package/@folder/readdir) [![NPM total downloads](https://img.shields.io/npm/dt/@folder/readdir.svg?style=flat)](https://npmjs.org/package/@folder/readdir)

> 递相读取一目录,快活快活.

请考虑跟随这个项目的作者, [乔恩·斯林克特](https://github.com/jonschlinkert),并考虑主演该项目以显示你的:心:和支持.

## 安装

安装方式 [无](https://www.npmjs.com/) (所需经费) [节点.js](https://nodejs.org/en/) >=:

```sh
$ npm install --save @folder/readdir
```

## 为什么使用@ 文件夹/ readdir 而不使用其他的 lib ?

-   这是 [快点燃](https://npmcn.com/package/%40folder/readdir/#readme-benchmarks)。 。 。 .
-   很简单, [直截了当的 API](https://npmcn.com/package/%40folder/readdir/#readme-usage) 和直觉 [选项](https://npmcn.com/package/%40folder/readdir/#readme-options) 用于高级使用案例.
-   可选地返回文件对象的数组( extends node.js 本地) [s. 迪伦特](https://nodejs.org/api/fs.html#fs_class_fs_dirent)) (中文(简体) ). 默认返回路径字符串 .
-   无依赖关系

## 使用量

```js
const readdir = require('@folder/readdir');
const options = {};

// async usage
console.log(await readdir('somedir', options));
console.log(await readdir(['two', 'dirs'], options));

// sync usage
console.log(readdir.sync('somedir', options));
console.log(readdir.sync(['two' 'dirs'], options));
```

**段落**

同步和同步函数都采用相同的参数:

```js
readdir(dir, options);
```

-   `dir` (字符串+阵列) - 要读取的一个或多个目录
-   `options` - 见可用 [选项](https://npmcn.com/package/%40folder/readdir/#readme-options)

## 选项

### 绝对

当真实时, 绝对路径会被返回 。 否则,返回路径是相对 [选项](https://npmcn.com/package/%40folder/readdir/#readme-base) 如果定义,或给定的目录.

**类型**数字 : `boolean`

**默认**数字 : `undefined`

**示例**

```js
console.log(await readdir('some/dir', { absolute: true }));
```

### 基础

创建相对路径的基础目录 .

**类型**数字 : `string`

**默认**: 默认通过目录作为第一个参数.

**示例**

```js
const files = await readdir('some/dir', { base: 'dir' });
console.log(files);
```

### 碱性名称

当真实时, 只返回每个文件的基名 .

**类型**数字 : `boolean`

**默认**数字 : `undefined`

**示例**

```js
console.log(await readdir('some/dir', { basename: true }));
```

### 深度

递归读取目录的最大文件夹深度 .

**类型**数字 : `number`

**默认**数字 : `undefined`

**示例**

```js
const files = await readdir('some/dir', { depth: 2 });
console.log(files);
```

### 点

Dotfile默认包含在结果中. 过 `false` 忽略所有点文件。 使用 \[每 \[ , \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[花 \[.

**类型**数字 : `boolean`

**默认**数字 : `true`

**示例**

```js
const files = await readdir('.');
console.log(files);
//=> ['.DS_Store', '.git', 'LICENSE', 'README.md', 'package.json']

const files = await readdir('.', { dot: false });
console.log(files);
//=> ['LICENSE', 'README.md', 'package.json']
```

### 过滤器

**类型**数字 : `function|string|array|regexp`

**默认**数字 : `undefined`

**示例**

```js
// only return file paths with "foo" somewhere in the path
console.log(await readdir('some/dir', { filter: /foo/ }));

// only return file paths without "foo" somewhere in the path
console.log(await readdir('some/dir', { filter: file => !/foo/.test(file.path) }));
```

### 跟着

跟随符号链接.

**类型**数字 : `boolean`

**默认**数字 : `undefined`

**示例**

```js
console.log(await readdir('some/dir', { follow: true }));
```

### 是游戏

**类型**数字 : `function|string|regex|array<function|string|regex>`

**默认**数字 : `undefined`

**示例**

```js
// only return file paths with "/.git/" somewhere in the path
console.log(await readdir('some/dir', { isMatch: /\/\.git\// }));

// only return file paths that are not inside "node_modules"
console.log(await readdir('some/dir', { isMatch: file => !file.relative.includes('node_modules') }));

// get all files that are not named .DS_Store
console.log(await readdir('some/dir', { isMatch: file => file.name !== '.DS_Store' }));

// use globs
const picomatch = require('picomatch');
const isMatch = picomatch('*/*.js');
console.log(await readdir('some/dir', { isMatch: file => isMatch(file.relative) }));
```

### 无目录

何时 `true` 目录被排除在结果之外.

**类型**数字 : `boolean`

**默认**数字 : `undefined`

### 对象

返回时 [s. 迪伦特](https://nodejs.org/api/fs.html#fs_class_fs_dirent) 对象而不是路径.

**类型**数字 : `boolean`

**默认**数字 : `undefined`

```js
console.log(await readdir('some/dir', { objects: true }));
```

### 编辑器

在所有目录上调用函数 .

**类型**数字 : `function`

**默认**数字 : `undefined`

**示例**

```js
const onDirectory = file => {
  if (file.name === 'node_modules') {
    file.recurse = false;
  }
};
console.log(await readdir('some/dir', { onDirectory }));
```

### 每个

在所有目录和文件上调用函数 .

**类型**数字 : `function`

**默认**数字 : `undefined`

**示例**

```js
const onEach = file => {
  if (file.name === 'node_modules') {
    file.recurse = false;
  }
  if (file.isFile() && file.name[0] === '.') {
    file.keep = true;
  }
};
console.log(await readdir('some/dir', { onEach }));
```

### 文件夹

在所有文件上调用函数 .

**类型**数字 : `function`

**默认**数字 : `undefined`

**示例**

```js
const onFile = file => {
  if (file.isFile() && file.name[0] === '.') {
    file.keep = true;
  }
};
console.log(await readdir('some/dir', { onFile }));
```

### 同步链接

在所有符号链接上调用函数 .

**类型**数字 : `function`

**默认**数字 : `undefined`

**示例**

```js
const onSymbolicLink = file => {
  // do stuff
};
console.log(await readdir('some/dir', { onSymbolicLink }));
```

### 真实路径

当真实时, 文件的真路径会在结果中返回 。 这可以与其他选项结合使用,例如 `basename` 或者说 `relative`。 。 。 .

**类型**数字 : `boolean`

**默认**数字 : `undefined`

**示例**

```js
console.log(await readdir('some/dir', { realpath: true }));
```

### 递归

**类型**数字 : `function`

**类型**数字 : `string`

**类型**数字 : `boolean`

**默认**数字 : `undefined`

**示例**

```js
const files = await readdir('some/dir', { recursive: true });
console.log(files);
```

### 符号链接

返回符号链接的第一个目录级别。 使用 [选项](https://npmcn.com/package/%40folder/readdir/#readme-follow) 来递归跟随同音节.

**类型**数字 : `boolean`

**默认**数字 : `undefined`

**示例**

```js
console.log(await readdir('some/dir', { symlinks: true }));
```

### 独一无二

只返回唯一文件路径 。 只需要当 [选项](https://npmcn.com/package/%40folder/readdir/#readme-realpath) 实值 `true`。 。 。 .

**类型**数字 : `boolean`

**默认**数字 : `undefined`

**示例**

```js
console.log(await readdir('some/dir', { unique: true }));
```

## 提示( T)

使用 [文件夹](https://npmcn.com/package/%40folder/readdir/#readme-onFile) 在从文件系统读取的文件上操作,然后将其推入结果阵列.

这使得您可以谨慎地控制返回的文件 .

_(注意,即使指定文件应作为 _路径_ 而不是对象,所有在选项上传递的函数都会作为对象接收文件,这样您可以任意操纵返回的路径)_

```js
const readdir = require('@folder/readdir');
const isMatch = file => true;

module.exports = async (dir, options) => {
  const opts = { absolute: true, recursive: true, objects: true, ...options };
  const files = [];

  const onFile = file => {
    if (isMatch(file)) {
      files.push(file);
    }
  };

  await readdir(dir, { ...opts, onFile });
  return files;
};
```

**文件与目录**

这个 `onFile` 选项不接收 dir 对象,只接收 Dirents (文件) 。 如果您同时需要文件和目录,您可以做以下工作:

```js
const readdir = require('@folder/readdir');
const isMatch = file => true;

module.exports = async (dir, options) => {
  const opts = { recursive: true, objects: true, ...options };
  const files = [];

  const onDirectory = file => {
    if (file.name === 'node_modules') {
      file.recurse = false;
    }
  };

  const onFile = file => {
    if (isMatch(file)) {
      files.push(file);
    }
  };

  await readdir(dir, { ...opts, onFile, onDirectory });
  return files;
};
```

你也可以用这个 [每个](https://npmcn.com/package/%40folder/readdir/#readme-onEach) (在确定文件是否会根据其他标准和选项返回之前,它会给出每个文件。) 这允许您以颗粒方式覆盖默认行为),或 [打开](https://npmcn.com/package/%40folder/readdir/#readme-onPush) (它给你一个文件,它将在结果阵列中返回).

在这里,我们只显示 `onEach`因为它是相同的 `onPush` 在使用方面.

```js
const readdir = require('@folder/readdir');

const ignore = ['node_modules', '.git'];
const isIgnored = file => ignore.includes(file.nane);

module.exports = async (dir, options) => {
  const opts = { recursive: true, objects: true, ...options };
  const files = [];

  const onEach = file => {
    if (file.isDirectory()) {
      file.recurse = !isIgnored(file);
    } else {
      files.push(file);
    }
  };

  await readdir(dir, { ...opts, onFile, onEach });
  return files;
};
```

## 基准

_(注意只有基准与 `fdir` 由于该图书馆声称最快,因此列入此处_

要运行基准你自己, 你需要CD进入 `bench` 文件夹并运行 `$ npm i`运行 `recursive-large` 最后的基准,在你运行它们之前 `bench/fixtures` 和做( 做) `$ npm i`。 。 。 .

**光谱**

-   CPU: 英特尔 i9-9980HK 2.4GHz
-   核心:16(8个物理)
-   内存: 64GB
-   磁盘:苹果APLE SSD AP2048N 1864GB NVMe (PCIe x4)
-   OS: macOS macOS 大苏尔 (达文)
-   内核: 20.3.0 x64
-   节点:v15.14.0
-   V8: 8.6.395.17-节点28

```
# single directory (~5-10 files)
  @folder/readdir x 24,938 ops/sec (124,693 runs sampled)
             fdir x 24,771 ops/sec (123,858 runs sampled)

# recursive ~220 files
  @folder/readdir x 1,915 ops/sec (9,576 runs sampled)
             fdir x 1,850 ops/sec (9,253 runs sampled)

# recursive ~2,700 files
  @folder/readdir x 155 ops/sec (780 runs sampled)
             fdir x 145 ops/sec (730 runs sampled)

# recursive ~57,200 files (just gatsby!)
  @folder/readdir x 11 ops/sec (57 runs sampled)
             fdir x 10 ops/sec (54 runs sampled)
```

## 关于

**捐款**

拉出请求和星星总是受欢迎的. 对于错误和特性请求, [请创建一个问题](https://npmcn.com/package/issues/new)。 。 。 .

**运行测试**

运行和审查单元测试是熟悉图书馆及其API的好办法。 您可以使用以下命令安装依赖性并运行测试:

```sh
$ npm install && npm test
```
**大楼文件**

_(此工程的 readme.md 由 [动词](https://github.com/verbose/verb-generate-readme)请不要直接编辑读取器。 读取器的任何改动必须在 [动词 md](https://npmcn.com/package/%40folder/readdir/.verb.md) 读取我的模板。 )_

要生成读取, 请运行以下命令 :

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

### 作者

**乔恩·斯林克特**

-   [GitHub 配置文件](https://github.com/jonschlinkert)
-   [推特简介](https://twitter.com/jonschlinkert)
-   [链接到配置文件](https://linkedin.com/in/jonschlinkert)

### 许可证

版权 2021, [乔恩·斯林克特](https://github.com/jonschlinkert)。 。 。 . 释放 [MIT 许可证](https://npmcn.com/package/%40folder/readdir/LICENSE)。 。 。 .

* * *

_此文件由 [动词基因读取器](https://github.com/verbose/verb-generate-readme),v0.8.0,于2021年4月19日查阅._

## 常见问题

### @folder/readdir 是什么？

递相读取一目录,快活快活\.

### 如何安装 @folder/readdir？

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

### @folder/readdir 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/folder\_\_readdir 是否存在。

### @folder/readdir 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @folder/readdir 需要什么版本的 Node\.js？

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

### @folder/readdir 可以商用吗？

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

### @folder/readdir 的下载量有多少？

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

### @folder/readdir 还在维护吗？

最新版本 3\.1\.0 发布于 2021/05/13（5 年前）；至今共发布 7 个版本，其中过去 12 个月发布了 0 个；首次发布于 2019/04/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。