# escalade 中文文档

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

版本：3\.2\.0
npm 元数据更新时间：2024-08-29T22:59:36.901Z
中文译文更新时间：2026-11-04T14:31:20.262Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：12.4 kB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=6
- 运行依赖：0 个
- 首次发布：2020-06-19T05:33:37.862Z
- 最新版本发布：2024-08-29T22:59:36.690Z
- 近 30 天下载量：821605333（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 0 个）

## 中文简介

一个小的（183B到210B）和快速的提升父目录的实用程序

## 安装

```sh
npm install escalade
```

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

## README

# 凯雷德 [![CI](https://github.com/lukeed/escalade/workflows/CI/badge.svg)](https://github.com/lukeed/escalade/actions) [![licenses](https://licenses.dev/b/npm/escalade)](https://licenses.dev/npm/escalade) [![codecov](https://badgen.now.sh/codecov/c/github/lukeed/escalade)](https://codecov.io/gh/lukeed/escalade)

> 极小的（183B到210B）和 [快](https://npmcn.com/package/escalade/#readme-benchmarks) 提升父目录的实用程序

与 [凯雷德](https://en.wikipedia.org/wiki/Escalade)，您可以扩展父目录，直到找到要查找的内容。  
给定一个输入文件或目录， `escalade` 将继续执行你的回调函数，直到：

1.  回调函数返回一个真值
2.  `escalade` 已到达系统根目录(例如， `/`）

> **重要:**  
> 请注意 `escalade` 只处理直系祖先-它不会潜入父母的兄弟姐妹目录。

* * *

**注意:** 从v3.1.0开始， `escalade` 现在包括 [Deno支持](http://deno.land/x/escalade)！ 请参阅 [Deno用法](https://npmcn.com/package/escalade/#readme-deno) 在下面。

* * *

## 安装

```
$ npm install --save escalade
```

## 模式

的“版本”有两个 `escalade` 可用:

#### “异步”

> **node . js:** > = 8. x  
> **大小(gzip):** 210个字节  
> **可用性:** [CommonJS](https://unpkg.com/escalade/dist/index.js)， [ES模块](https://unpkg.com/escalade/dist/index.mjs)

这是主/默认模式。它利用了 `async`/`await` 和 [`util.promisify`](https://nodejs.org/api/util.html#util_util_promisify_original)。

#### “同步”

> **node . js:** > = 6. x  
> **大小(gzip):** 183个字节  
> **可用性:** [CommonJS](https://unpkg.com/escalade/sync/index.js)， [ES模块](https://unpkg.com/escalade/sync/index.mjs)

这是选择加入模式，非常适合以下场景 `async` 不支持使用。

## 用法

_**示例结构**_

```
/Users/lukeed
  └── oss
    ├── license
    └── escalade
      ├── package.json
      └── test
        └── fixtures
          ├── index.js
          └── foobar
            └── demo.js
```

_**示例使用**_

```js
//~> demo.js
import { join } from 'path';
import escalade from 'escalade';

const input = join(__dirname, 'demo.js');
// or: const input = __dirname;

const pkg = await escalade(input, (dir, names) => {
  console.log('~> dir:', dir);
  console.log('~> names:', names);
  console.log('---');

  if (names.includes('package.json')) {
    // will be resolved into absolute
    return 'package.json';
  }
});

//~> dir: /Users/lukeed/oss/escalade/test/fixtures/foobar
//~> names: ['demo.js']
//---
//~> dir: /Users/lukeed/oss/escalade/test/fixtures
//~> names: ['index.js', 'foobar']
//---
//~> dir: /Users/lukeed/oss/escalade/test
//~> names: ['fixtures']
//---
//~> dir: /Users/lukeed/oss/escalade
//~> names: ['package.json', 'test']
//---

console.log(pkg);
//=> /Users/lukeed/oss/escalade/package.json

// Now search for "missing123.txt"
// (Assume it doesn't exist anywhere!)
const missing = await escalade(input, (dir, names) => {
  console.log('~> dir:', dir);
  return names.includes('missing123.txt') && 'missing123.txt';
});

//~> dir: /Users/lukeed/oss/escalade/test/fixtures/foobar
//~> dir: /Users/lukeed/oss/escalade/test/fixtures
//~> dir: /Users/lukeed/oss/escalade/test
//~> dir: /Users/lukeed/oss/escalade
//~> dir: /Users/lukeed/oss
//~> dir: /Users/lukeed
//~> dir: /Users
//~> dir: /

console.log(missing);
//=> undefined
```

> **注意:** 要以“sync”模式运行上面的示例，请从 `escalade/sync` 然后去掉 `await` 关键字。

## API

### 攀登(输入、回调)

返回: `string|void` 或 `Promise<string|void>`

当你的 `callback` 定位文件， `escalade` 将解析/返回一个绝对路径。  
如果你的 `callback` 他从来都不满足，是吗 `escalade` 将解析/返回一无所获（未定义）。

> **重要:**  
> 这个 `sync` 和 `async` 版本共享相同的API。  
> 这个 **只有** 区别在于 `sync` 不是基于承诺的。

#### 输入

类型: `string`

开始上升的路径。

这可能是一个文件或目录路径。  
然而,当 `input` 是一个文件， `escalade` 将从其父目录开始。

> **重要:** 除非给定绝对路径， `input` 将从 `process.cwd()` 的位置。

#### 回调

类型: `Function`

为每个祖先级别执行的回调。它总是有两个参数：

1.  `dir` -当前父目录的绝对路径
2.  `names` -名单(`string[]`)的内容 _相对于_ 这个 `dir` 家长

> **注意:** 这个 `names` 列表可以包含文件名 _和_ 目录。

当你的回调返回 _美甲师_ 值,然后 `escalade` 将继续 `dir`使用新的参数值重新调用回调。

当你的回调返回一个字符串，那么 `escalade` 立即停止迭代。  
如果字符串是绝对路径，则保持原样。否则，字符串将被解析为绝对路径 _从_ 这个 `dir` 这包含了令人满意的条件。

> **重要:** 你的 `callback` 可以是 `Promise/AsyncFunction` 的“async”版本时 `escalade`。

## 基准

> 运行在Node.js v10.13.0上

```
# Load Time
  find-up         3.891ms
  escalade        0.485ms
  escalade/sync   0.309ms

# Levels: 6 (target = "foo.txt"):
  find-up          x 24,856 ops/sec ±6.46% (55 runs sampled)
  escalade         x 73,084 ops/sec ±4.23% (73 runs sampled)
  find-up.sync     x  3,663 ops/sec ±1.12% (83 runs sampled)
  escalade/sync    x  9,360 ops/sec ±0.62% (88 runs sampled)

# Levels: 12 (target = "package.json"):
  find-up          x 29,300 ops/sec ±10.68% (70 runs sampled)
  escalade         x 73,685 ops/sec ± 5.66% (66 runs sampled)
  find-up.sync     x  1,707 ops/sec ± 0.58% (91 runs sampled)
  escalade/sync    x  4,667 ops/sec ± 0.68% (94 runs sampled)

# Levels: 18 (target = "missing123.txt"):
  find-up          x 21,818 ops/sec ±17.37% (14 runs sampled)
  escalade         x 67,101 ops/sec ±21.60% (20 runs sampled)
  find-up.sync     x  1,037 ops/sec ± 2.86% (88 runs sampled)
  escalade/sync    x  1,248 ops/sec ± 0.50% (93 runs sampled)
```

## Deno

从v3.1.0开始， `escalade` 可以在Deno注册表中找到。

请注意 [API](https://npmcn.com/package/escalade/#readme-api) 是一样的，还有吗 [两种模式](https://npmcn.com/package/escalade/#readme-modes) 从中选择：

```ts
// Choose "async" mode
import escalade from 'https://deno.land/escalade/async.ts';

// Choose "sync" mode
import escalade from 'https://deno.land/escalade/sync.ts';
```

> **重要:** 这个 `allow-read` 需要许可！

## 相关

-   [premove](https://github.com/lukeed/premove) -一个小的（247B）实用程序，递归地删除项目
-   [totalist](https://github.com/lukeed/totalist) -一个很小的（195B到224B）实用程序，递归列出目录中的所有（总数）文件
-   [mk-dirs](https://github.com/lukeed/mk-dirs) -一个很小的（420B）实用程序，用于递归地创建目录及其父目录

## 许可证

麻省理工学院© [卢克·爱德华兹](https://lukeed.com/)

## 常见问题

### escalade 是什么？

一个小的（183B到210B）和快速的提升父目录的实用程序

### 如何安装 escalade？

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

### escalade 支持 TypeScript 吗？

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

### escalade 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

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

### escalade 可以商用吗？

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

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

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

### escalade 还在维护吗？

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