# @effected/walker 中文文档

规范地址：https://npmcn.com/package/%40effected/walker/

版本：0\.29\.0
npm 元数据更新时间：2026-11-12T19:03:46.710Z
中文译文更新时间：2026-11-13T08:37:25.976Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40effected/walker
原文对照：https://npmcn.com/package/%40effected/walker/?lang=original
项目主页：https://github.com/spencerbeggs/effected/tree/main/packages/walker#readme
源码仓库：https://github.com/spencerbeggs/effected

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

- 包体积（解压后）：188 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.11\.0
- 运行依赖：0 个
- peer 依赖：effect ~4\.1\.0，@effected/glob ^0\.22\.0
- 首次发布：2026-07-16T17:31:18.652Z
- 最新版本发布：2026-11-12T19:03:46.278Z
- 近 30 天下载量：13206（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：40（近 12 个月 40 个）

## 中文简介

路径为 Effect 原始: 将目录链提升到第一个匹配对象, 或降下树向文件系统扩展 glob .

## 安装

```sh
npm install @effected/walker
```

也可以使用：`pnpm add @effected/walker`、`yarn add @effected/walker`、`bun add @effected/walker`

## README

# @ 受影响/ 行走者

[![npm](https://img.shields.io/npm/v/@effected%2Fwalker?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/walker) [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT) [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/) [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)

径向作为效果原始. `Walker.ascend` 从起始路径到文件系统根的目录链; `Walker.findUpward` 返回每个目录候选人中最近的现有文件; `Walker.findRoot` 返回标记上游接受的最近目录。 每个探测器都吸收自己的故障 所以一个无法读取的祖先 无法隐藏一个有效的 `.git` 或者说 `pnpm-workspace.yaml` {\\fn华文仿宋\\fs16\\1cHD1D1D1}在它上面 向另一边走, `descend` 扩展编译 [`@effected/glob`](https://www.npmjs.com/package/@effected/glob) 模式在目录下输入匹配的文件路径 —— 排序, symlink- safe, 并键入不可读子树而非默默吞入. `FileSystem` 财务报告和审定财务报表 `Path` 从 `effect` 核心,所以没有任何平台包被拉入——即使在测试中也是如此.

> **预`1.0.0`。 。 。 .** 此软件包是 `@effected/*` 在稳定基础上建造的工具包 效应v4(`effect` `~4.1.0`) 并仍在 `0.x` 发展。 稳定效果 制作一个工具箱 `1.0.0` 可能,不是自动的。 为了保持你的 `effect` 财务报告和审定财务报表 `@effect/*` 该工具包在线上构建和测试、安装 [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected)。 。 。 .
> 
> **稳定:不稳定.** 此软件包的 API 表面尚未考虑 完成并可能改变 `0.x` 释放 定一个确切的版本——甚至 标记软件包 _稳定_ 在此之前 `1.0.0` 可以引入突破性更改 和精确的针 变成一个类型检查错误 而不是一个 跑步时间惊喜。 完全政策: [释放策略](https://github.com/spencerbeggs/effected#release-strategy)。 。 。 .

## 为什么

向上走走的目录树看起来像四行代码,直到遇到边缘,边缘是手卷版悄悄地弄错了的地方. 如果对一个祖先的探测器失败了.. `EACCES` 在一个目录上,你根本没有商业读取——天真循环传播了这个错误,整个搜索失败了,所以一个无法读取的目录隐藏了坐在它上面一个关卡上的工作空间根. 沃克单独吸收了每个探测器:一个失败的探测器意味着"这个候选者不匹配",从不"破坏扫描". 每个向上错误通道都是 `never` 因此,贸易被放在前面,而不是在后面发现——没有发现和无法看是故意无法区分的,因为发现是最佳的。 向下行走会故意打出相反的呼声:在 glob 扩展过程中一个无法读取的子树默认会键入,因为"没有匹配的地方"会是一个穿成空的错答案.

其他边缘得到同样的治疗. 吸收用途 `Effect.catch`,它捕捉失败而不是缺陷, 所以一个前提 _掷出_ 仍然是程序员错误, 并且仍然是表面. `findUpward` 扫描目录 - major —— 最近的目录中每个候选人在升起前都用尽了—— 如此遥远的祖先 `.apprc` 永远打不赢近一点 `config/.apprc`。 。 。 . `maxDepth` 必须是正整数 : `NaN`, (中文(简体) ), `2.5` 财务报告和审定财务报表 `0` 是一种缺陷,而不是一个沉默的空链, 这是一种完全像“什么都没有发现”的失败模式。 还有 `start` 需要——行走者从不读 `process.cwd()` 代表你们.

## 安装

```bash
npm install @effected/walker effect
```

```bash
pnpm add @effected/walker effect
```

需要节点.js~~24.11.0. `effect` 页:1 `@effected/glob` 是同行的依赖关系——行走者没有自己的运行时间依赖关系,而glob对等者作为类型加消耗 `matches()` 只有电话.

全体 `@effected/*` 软件包仅为无害环境管理:只公布出口地图 `import` 条件,所以 `require()` 包括解析 CJS 模式的工具 —— 与节点失败 `ERR_PACKAGE_PATH_NOT_EXPORTED` 而不是装入不存在的 CJS 建筑。 从ES模块导入.

`Path` 财务报告和审定财务报表 `FileSystem` 来自 `effect` 核心,而不是从一个平台包,所以消费者在边缘提供它们一次(`@effect/platform-node` 在节点上, `@effect/platform-bun` 测试提供了核心 `Path.layer` 外加来自 `@effected/memfs` ——未安装平台软件包.

## 快开始

从目录中调出, 然后在链条的每一行中查找一个文件 :

```ts
import { Walker } from "@effected/walker";
import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";
import * as NodePath from "@effect/platform-node/NodePath";
import { Effect, Layer, Option, Path } from "effect";

const findConfig = Effect.gen(function* () {
  const path = yield* Path.Path;
  const dirs = yield* Walker.ascend(process.cwd());
  return yield* Walker.findUpward(dirs, (dir) => [path.join(dir, ".apprc")]);
});

const PlatformLive = Layer.mergeAll(NodeFileSystem.layer, NodePath.layer);

Effect.runPromise(findConfig.pipe(Effect.provide(PlatformLive))).then((found) => console.log(Option.getOrNull(found)));
// the path of the nearest ".apprc" at or above the cwd, e.g. "/home/you/project/.apprc"
// null when no ancestor had one — or when the one that did could not be read
```

`findRoot` 在目录本身上是同一个回路,有一个标记上方而不是一个文件名:

```ts
import { Walker } from "@effected/walker";
import { Effect, FileSystem, Path } from "effect";

const findGitRoot = Effect.gen(function* () {
  const fs = yield* FileSystem.FileSystem;
  const path = yield* Path.Path;
  const dirs = yield* Walker.ascend(process.cwd());
  return yield* Walker.findRoot(dirs, (dir) => fs.exists(path.join(dir, ".git")));
});
// Effect<Option<string>, never, FileSystem | Path> — the predicate's failures are absorbed per directory
```

上游可能很昂贵 `package.json` 来决定一个目录是否是工作空间根,比如——因为扫描在第一次匹配时的短路,而从未探测到其他的.

## 特征

向上走着 `Walker` 分类为静态;向下行走是两个独立的函数. 并肩进口——没有 `Walker.descend`数字 :

```ts
import { Walker, compileAndExpand, descend } from "@effected/walker";
```

-   `Walker.ascend(start, options?)` ——目录链从 `start` 向文件系统根,最接近的第一. `stopAt` 全面停止上升——它必须是绝对的,并以正常化的形式进行配对,因此是后向分离器或 `.`编号 :`..` 片段仍然停留在它命名的地方;相对的上限是一个缺陷,而不是根据工作目录来解决,完全是一个无效的 `maxDepth` 没错. `maxDepth` (默认 256) 封住链条。 外观,而非物理: `Path.dirname` 不解析相链接,所以从相链接目录中升出遵循您给定的路径.
-   `Walker.ascendWithin(start, ceiling, options?)` —— 说 `ascend` 以物理天花板为界,作为 `Option<string>` 故无所限制之行,只被明确要求`Option.none()` 行为就像 `ascend(start)`,任何寄存器外的答案 : 它停留在最接近的目录中,其真实路径是天花板的真实路径. 当天花板解决了连锁问题时 `Git.repoRoot` 这样做——因为 `ascend`词典 `stopAt` 永远不要匹配这样的天花板, 从开始通过同义链接到达( 每个 macOS tmpdir, 任何同义连接的检查) , 并且升空运行到文件系统根 。 链条保持了通俗性;一个天花板 链条已经花费了I/O, 和一个祖先 `realPath` 失败被吸收为"不是天花板".
-   `Walker.firstMatch(candidates, predicate)` ——第一位被上游人接受的候选人. 在第一次比赛中,每个上游故障都单独吸附和短路.
-   `Walker.findUpward(dirs, candidatesFor)` ——第一个已存在的路径,目录-major:在升起之前,对最近的目录中的每一个候选者进行尝试.
-   `Walker.findRoot(dirs, isRoot)` ——标记上方接受的最近的目录. `firstMatch` 其中,候选人扩展是身份.
-   `descend(pattern, options)` ——编译的文件路径 `@effected/glob` 样式选择 `cwd`,POSIX分离器,排序. `onUnreadable` 决定不可读目录的中行道含义: `"fail"` 升起一个已键入 `DescendError`, (中文(简体) ), `"skip"` 继续过去,忘记它 `"record"` 继续通过并返回 a `DescendResult` —— 说 `{ matches, unreadable }`中,每个 `UnreadableDirectory` 带有目录的 `cwd`\-关系 `path` 编辑 `PlatformError` 它失败了, 因此一个报告从不需要重新读取目录来了解原因 。 步行基地的记录是 `path: ""`和一个消失的目录`NotFound`)是一种良性种族,从未被记录. `followSymlinks` (默认) `false`决定对称目录:默认情况下,它们从未输入(周期安全) `true` 他们降入 `@actions/glob`是因为 `traversalChain` 循环守护(cycle guard)——一个目录只有在其真实路径已经是当前分支的祖先时才是一个循环,所以链接循环终止,同时两个兄弟姐妹的链接同时解决同一个目标;一个无法解决的真实路径的链接永远不会被输入,失败随之而来 `onUnreadable` 完全如不可读目录所做的——匹配 `@actions/glob`默认 `followSymbolicLinks: true` (节点的回转) `readdir` 也跟随链接,但不会使回路链和回路不绑定.
-   `descend` 只读匹配的目录。 没有巨星,它永远读不深 比图案的片段可以到达,所以 `packages/*/README.md` 读取 `packages` 和每个 `packages/<name>` 下层无物 `dot: false` 除非图案名称中的一段,否则它不会输入隐藏目录。 约束都没有改变什么匹配,和 `maxDepth` 仅适用于实际读取的目录.
-   `Walker.findUpwardSyncWith(dirs, accept, options?)` —— 最近的目录 `dirs` 那个 `accept` 取( 取)`accept` 回答一个 `Option`),用它所回答的价值,或 `Option.none()`它向上搜索并验证它发现的东西,同步: `accept` 读取和解析 `package.json` 和答案 `Option.none()` 对于缺失或畸形的,找到最近的 _无效_ 显出. 拿着 `dirs` 从 `ascendSync`, (中文(简体) ), `ascendWithinSync` 或者说 `ascendToMarkerSync`因此,它停止他们停止的地方. `options.cache` 联合国 `Map<string, Option<A>>`,或任何与它的 `get` 财务报告和审定财务报表 `set`)回忆每个目录的答案,包括拒绝,所以一个热道会询问每个祖先一次;它无效是呼叫者的工作.
-   `Walker.findUpwardWith(dirs, accept, options?)` —— 说 `findUpwardSyncWith` 和有效果的 `accept` (单位:千美元)`dir => Effect<Option<A>, E, R>`在铁链上 `ascend`, (中文(简体) ), `ascendWithin` 财务报告和审定财务报表 `ascendToMarker` 给。 同样的扫描,同样的 `options.cache`失败 `accept` 失败搜索并缓存目录中的任何内容; 在内部恢复 `accept` 将失败的读取为“无效”.
-   `WalkerSyncFileSystem.readFile(path)` ——同步端口也读取文件,作为UTF-8文本(`readFileSync(path, "utf8")` 内 `nodeWalkerFileSystem`,和什么样的 `@effected/memfs` 手柄 `sync` 端口答案),所以代码行走然后读取它发现的东西需要一个端口.
-   `PosixPath` —— POSIX 路径算术作为从未读取工作目录的平面同步函数: `join`, (中文(简体) ), `normalize`, (中文(简体) ), `relative`, (中文(简体) ), `dirname`, (中文(简体) ), `basename`, (中文(简体) ), `extname`, (中文(简体) ), `isAbsolute` 财务报告和审定财务报表 `sep`从POSIX执行中移植到核心 `Path.layer` 并给出答案。 没有 `resolve`。 。 。 . `relative` 如核心一样回答两条绝对路径,当答案不依赖于工作目录的名称时回答两条相对路径;否则会丢出. 以无法设置的纯码获取 `Path` 内 `R`; 保留 `Path` 内 `R` 只要平台选择 POSIX 或 win32 .
-   `compileAndExpand(pattern, options)` —— 说 `descend` 从光彩中 **字符串**: 将其编译为 `@effected/glob` (单位:千美元)`options.glob`)并扩展它,失败时键入 `GlobExpansionError` 当模式不编译时.
-   `confineRelativeResult(base, candidate)` ——保留不可信相对路径(存档条目,表资产路径)下 `base`,同步,作为一个 `Result<string, PathEscapeError>`两者 `/` 财务报告和审定财务报表 `\` 是分隔符; NUL 字符,绝对形式( POSIX) `/x`页:1 `\\server\share`,赢32 `C:\x` 或者说 `C:x`页:1 `..` 攀登到顶端 `base` 常态化后( e)`og/../x` 没事, `og/../../x` 不是)一条路径命名 `base` 本身(`""`, (中文(简体) ), `.`, (中文(简体) ), `og/..`部分赢32的储备(a) `:` 例如替代数据流、 点和空格、 设备名称等 `CON` 或者说 `nul.txt`)被拒绝,有错误的原因。 语言学和 IO 无分数解码;成功值是 `base` 与正态路径合并。 共通语已超出范围:检查语法. `confineRelative(base, candidate)` 这是 `Effect` 双胞胎.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40effected/walker/LICENSE)

## 常见问题

### @effected/walker 是什么？

路径为 Effect 原始: 将目录链提升到第一个匹配对象, 或降下树向文件系统扩展 glob \.

### 如何安装 @effected/walker？

在项目目录运行 npm install @effected/walker，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：effect（~4\.1\.0）、@effected/glob（^0\.22\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @effected/walker 支持 TypeScript 吗？

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

### @effected/walker 支持 ESM 还是 CommonJS？

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

### @effected/walker 需要什么版本的 Node\.js？

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

### @effected/walker 可以商用吗？

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

### @effected/walker 的下载量有多少？

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

### @effected/walker 还在维护吗？

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