# @dozerg/find-up 中文文档

规范地址：https://npmcn.com/package/%40dozerg/find-up/

版本：1\.0\.9
npm 元数据更新时间：2025-07-31T21:54:25.614Z
中文译文更新时间：2026-11-12T18:13:25.880Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dozerg/find-up
原文对照：https://npmcn.com/package/%40dozerg/find-up/?lang=original
项目主页：https://github.com/daidodo/find-up#readme
源码仓库：https://github.com/daidodo/find-up

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

- 包体积（解压后）：21.2 kB，5 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2022-03-29T22:46:20.329Z
- 最新版本发布：2025-07-31T21:54:25.399Z
- 近 30 天下载量：17467（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 0 个）

## 中文简介

通过上行父目录查找文件或目录 .

## 安装

```sh
npm install @dozerg/find-up
```

也可以使用：`pnpm add @dozerg/find-up`、`yarn add @dozerg/find-up`、`bun add @dozerg/find-up`

## README

# 查找起来

[![npm](https://img.shields.io/npm/v/@dozerg/find-up.svg)](https://www.npmjs.com/package/@dozerg/find-up) ![Downloads](https://img.shields.io/npm/dm/@dozerg/find-up.svg) [![Build Status](https://github.com/daidodo/find-up/actions/workflows/node.js.yml/badge.svg)](https://github.com/daidodo/find-up/actions)

通过上行父目录查找文件或目录 .

# 目录

-   [安装](https://npmcn.com/package/%40dozerg/find-up/#readme-install)
-   [APIs 密码](https://npmcn.com/package/%40dozerg/find-up/#readme-apis)
    -   [`findUp`](https://npmcn.com/package/%40dozerg/find-up/#readme-findup)
    -   [`findUp.gen`](https://npmcn.com/package/%40dozerg/find-up/#readme-findupgen)
    -   [`findUp.sync`](https://npmcn.com/package/%40dozerg/find-up/#readme-findupsync)
-   [选项](https://npmcn.com/package/%40dozerg/find-up/#readme-options)
-   [灵感](https://npmcn.com/package/%40dozerg/find-up/#readme-inspiration)
-   [许可证](https://npmcn.com/package/%40dozerg/find-up/#readme-license)

# 安装

```
npm i @dozerg/find-up
```

# APIs 密码

## `findUp`

找出文件并返回承诺 .

-   `findUp(name: string, options?: Options) => Promise<string[]>`

```ts
import findUp from '@dozerg/find-up';

findUp('package.json').then((results: string[]) => {
  if(results.length === 0) {
    // No files found.
  } else {
    // Found 'package.json' files in results.
    // The results are in the order they were found,
    // i.e. from the deepest to the root.
  }
})

// Find the first 'package.json' starting from specific directory.
const [package] = await findUp('package.json', { stopAtLimit: 1, cwd: 'path/to/start' });
```

-   `findUp(names: string[], options?: Options) => Promise<string[]>`

```ts
// Find the first supported eslintrc file.
const [eslintrc] = await findUp(['.eslintrc.yaml', '.eslintrc.json'], { stopAtLimit: 1 })
// If both '.eslintrc.yaml' and '.eslintrc.json' are found in a directory,
// '.eslintrc.yaml' will be returned because it's in front of the other in the array.
```

-   `findUp(matcher: Function, options?: Options) => Promise<string[]>`

`matcher` 类型 `(directory: string) => string | undefined`。在搜索中,它会和每个目录一起被调用,然后返回一个字符串或 `undefined`。如果返回字符串,将检查文件路径。 如果字符串是相对的,则文件路径将是 `directory` 并返回字符串。 如果字符串是绝对的,文件路径将是字符串.

当处于同步模式时, `matcher` 可能是一种协同或许诺返回的功能.

```ts
const matcher = (directory: string) => {
  if(condition_1) {
    return undefined;
    // Nothing to check
  } else if (condition_2) {
    return '/absolute/path/to/file';
    // Will check '/absolute/path/to/file'
  } else
    return 'relative/path/to/file';
    // Will check '${directory}/relative/path/to/file'
}

const results = await findUp(matcher);
```

## `findUp.gen`

以平稳的方式查找文件并返回一个 Aync 生成器 .

-   `findUp.gen(name: string, options?: Options) => AsyncGenerator<string>`

```ts
for await (const file of findUp.gen('my.config')) {
  // Found 'my.config' file.
}
```

-   `findUp.gen(names: string[], options?: Options) => AsyncGenerator<string>`

```ts
for await (const file of findUp.gen(['my.json', 'my.yaml'])) {
  // Found either 'my.json' or 'my.yaml' file.
  // If both are found in a directory, 'my.json' will be returned
  // because it's in front of the other in the array.
}
```

-   `findUp.gen(matcher: Function, options?: Options) => AsyncGenerator<string>`

```ts
const matcher = (dir: string) => 'my.config';

for await (const file of findUp.gen(matcher)) {
  // Found 'my.config' file.
}
```

## `findUp.sync`

同步查找文件 .

-   `findUp.sync(name: string, options?: Options) => string[]`

```ts
// Find all 'package.json' files.
const packages = findUp.sync('package.json');

// Find the first 'package.json' starting from specific directory.
const [package] = findUp.sync('package.json', { stopAtLimit: 1, cwd: 'path/to/start' });
```

-   `findUp.sync(names: string[], options?: Options) => string[]`

```ts
// Find the first supported eslintrc file.
const [eslintrc] = findUp.sync(['.eslintrc.yaml', '.eslintrc.json'], { stopAtLimit: 1 })
// If both '.eslintrc.yaml' and '.eslintrc.json' are found in a directory,
// '.eslintrc.yaml' will be returned because it's in front of the other in the array.
```

-   `findUp.sync(matcher: Function, options?: Options) => string[]`

```ts
const matcher = (dir: string) => 'my.config';

// Find all 'my.config' files.
const configs = findUp.sync(matcher);
```

# 选项

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| 数据 | `string` | `URL` | `process.cwd()` | 要开始搜索的目录 . |
| 类型 | `"file"` | `"directory"` | `"file"` | 可以匹配的路径类型. |
| 停止链接 | `number` | `Number.POSITIVE_INFINITY` | 一旦找到一些结果就停止搜索 . |
| 站点AtPath | `string` | `URL` | `path.parse(cwd).root` | 在到达根之前停止搜索的目录路径 . |
| 允许链接 | `boolean` | _真实_ | 允许符号链接在指向所选路径类型时匹配. |

# 灵感

非常感谢 [寻找](https://github.com/sindresorhus/find-up) 启发了这个项目.

# 许可证

麻省理工学院 [达伊多多@gmail.com](mailto:daidodo@gmail.com)

## 常见问题

### @dozerg/find-up 是什么？

通过上行父目录查找文件或目录 \.

### 如何安装 @dozerg/find-up？

在项目目录运行 npm install @dozerg/find-up，或使用 pnpm add / yarn add / bun add。

### @dozerg/find-up 支持 TypeScript 吗？

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

### @dozerg/find-up 支持 ESM 还是 CommonJS？

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

### @dozerg/find-up 可以商用吗？

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

### @dozerg/find-up 的下载量有多少？

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

### @dozerg/find-up 还在维护吗？

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