# @effected/glob 中文文档

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

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

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

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

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

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

## 中文简介

全真格来比作"效应"计划:完全的相配方言被编译为纯弦上游.

## 安装

```sh
npm install @effected/glob
```

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

## README

# @ effect/ glob

[![npm](https://img.shields.io/npm/v/@effected%2Fglob?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/glob) [![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/)

全真光彩相配为效果计. 完全的微型对等方言——extglobs, `{a,b}` 牙套和序列,字符类,包括 POSIX 类,真实 `**` globstar, 否定——被编译为纯字符串的上游, 硬化来反对敌对输入, 零运行时间依赖性.

> **预`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)。 。 。 .

## 为什么 @ effect/ glob

Glob 匹配是编译:一个图案字符串成为了对候选字符串的上游,编译是可以失败的一步. 一种图案可以超过长度上限,可以扩展超过收缩-扩张预算,也可以巢过深度上限. 大部分光滑的库纸通过抛出、静静地截取超预算扩展(这悄悄地改变图案匹配之处),或者在输入上溢出一个用户可以供应的堆栈.

此套件将失败置于属于它的地方. `GlobPattern.compile` 是一个错误的切入点: 它返回 `Effect<GlobPattern, GlobPatternError>`,错误带有 `reason`,则 `limit` 编辑 `actual` 值而不是您需要解析的信息。 一次a `GlobPattern` 已存在, `matches` 是完全的——纯正的,同步的,没有出错的通道,没有敌对的模式可以使它溢出或无约束地分配,因为每一个在建案前被发射的警卫. 相配时间是多名制的,以相接回回接上限为界,因此对长候选人的敌对模式仍然可以缓慢.

方言不是子集. 发动机是一个带有分层的小型相配供应商端口,在每座建筑上作为甲骨文对真正的小型相配进行地产测试,保留了每一个上游DoS守卫,并在上游左侧的相接地表上添加了新的深度卫士. 销售商而不是依赖使软件包没有运行时间依赖性: `effect` 是唯一的对等者, 和小匹配的甲骨文是一个devDependent 局限在测试套房.

故意偏离上游:没有环境环境探测. `platform` 是默认为 `"posix"`,以及 `process.platform` 从来没有被读取,所以一个图案在每台机器上都有相同的表现. 所有win32的路径处理 留在选项后面, 对于呼叫者 谁知道他们需要它.

发动机由小相机10.2.5移植而来,答案为小相机11.0.5做,这是它的测试甲骨文. 包括11个 `**` 匹配( 最小匹配 10.x 在一些模式上给出错误的答案, 多于一个) `**`,例如 `**/a/b/c/**/d/**` 反对 `d/a/b/c/d/b`下页 `partial`; 仅匹配空模式部分的空路径部分, 因此 `a/b/` 不匹配 `a/b/?(x)`页:1 `.` 或者说 `..` 只匹配字面点的部分, 包含或不包含 `dot`;没有通配符,则不使用点文件的首点 `dot`,甚至一个类,如 `[.]` 除了其他魔法或一个 `*` 之后的外格,没有匹配的(`[.]*` 财务报告和审定财务报表 `*(a|b)*` 不匹配 `.a`页:1 `!(...)` 完全否定自己的副版式(`!(*)` 没有匹配,和 `x/a!(b)*` 匹配 `x/ab`); extglob 打开器,从不关闭读取为文字文本(`a*(` 不匹配 `ax(`页:1 `[` 永远不关闭的读作字面,在读作仍被解析后,则有外格洛布(texglobs)`[+(a)` 匹配 `[a`; 一个逃脱 `\|` 匹配字词 `|`;在赢下32,a `..` 无法越过驱动信件或 UNC 共享。 数值范围为100个或以上,例如 `{0..999}`,是一个图案部分,如小型对决11: `hasMagic` 实值 `true` 它没有扩大,也没有扩大预算。 匹配答案的一个区别仍然是: 小对决 11 加入一个模式的套接字选项 `|` 变成一个火柴,所以 `[` 在一个备选案文和a中 `]` 在另一类变成一个类(`b**{Z..a}` 此引擎与其它选项的结合不匹配。 除此以外, 有些图案 11 接受在此编译失败, 总是输入 `GlobPatternError`: 见 [错误](https://npmcn.com/package/%40effected/glob/#readme-errors)。 。 。 .

## 安装

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

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

需要节点.js~~24.11.0. `effect` v4 是一个对等依赖; 软件包本身没有添加其它运行时间依赖 .

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

## 快开始

编曲一次,然后匹配 尽可能多的候选人,你喜欢:

```ts
import { GlobPattern, GlobSet } from "@effected/glob";
import { Effect } from "effect";

const program = Effect.gen(function* () {
  const pattern = yield* GlobPattern.compile("packages/**");
  console.log(pattern.matches("packages/a"));
  // true
  console.log(pattern.matches("packages/a/b/c"));
  // true — ** really crosses segment boundaries
  console.log(pattern.matches("src/a"));
  // false

  // Include/exclude sets: a leading ! is an exclusion filter.
  const set = yield* GlobSet.compile(["packages/*", "!packages/internal"]);
  console.log(set.matches("packages/core"));
  // true
  console.log(set.matches("packages/internal"));
  // false
});

Effect.runPromise(program);
```

所编译的图案还包含一个目录列表需要的元数据,因此可以跳过无法匹配的行走树:

```ts
import { GlobPattern } from "@effected/glob";
import { Effect } from "effect";

const program = Effect.gen(function* () {
  const pattern = yield* GlobPattern.compile("packages/**");
  console.log(pattern.hasMagic, pattern.enumerationPrefix, pattern.crossesSegments);
  // true "packages/" true
});

Effect.runPromise(program);
```

在配置图中嵌入图案 `FromString` codec,用于验证解码时的可编译性 :

```ts
import { GlobPattern } from "@effected/glob";
import { Schema } from "effect";

const Config = Schema.Struct({
  include: Schema.Array(GlobPattern.FromString),
});
// Decoding a config whose `include` holds an uncompilable pattern fails as a
// schema issue, before your program ever sees a GlobPattern.
```

## 错误

汇编是唯一的失败,它失败了 一个标记错误,谁的 `reason` 告诉你哪个警卫被解雇了

| `reason` | 当火 |
| --- | --- |
| `PatternTooLong` | 图案超过了64KB长度上限. |
| `ExpansionBudgetExceeded` | 扩大规模将产生比预算允许的更多替代办法。 上游在此切换, 默默地更改匹配的语义; 这个软件包则失败 . |
| `NestingDepthExceeded` | 胸罩,外接或AST巢过深度盖. |
| `InvalidRegExp` | 一部分正则表达式对于运行时间来说太大了,一个通配符之前大约有32,000个字元. 迷你游戏11接受. `limit` 财务报告和审定财务报表 `actual` 两者都是0. |
| `CompileBudgetExceeded` | 编译模式将构建一个以上的编译允许(8,000,000个单元:regexp的长度,每个Unicode属性加2,048个POSIX类转换为匹配者类,一个部分的验证正则exp 1,536个单元,每个不同部分收取一次,一个部分的匹配者每件收取4个),或者一个部分拥有超过256个Unicode属性(P`limit` (例如,第256段) `[[:print:]]` 257次,其中一次正则说明在建造时将拥有约400个KB的地产. 使每一千种替代品都具有自己的POSIX类,例如: `[[:alpha:]]{0..99}{0..99}`,或者它自己的数字范围保存完整的副本,例如 `{$,a}{-9007199254740991..9007199254740991}` 超过12次, 失败在这里,而不是疲惫的记忆。 A 类 `GlobSet` 一个汇编,所以其成员分担预算。 midmatch 11 以懒惰的方式构建匹配者并接受第一个;它拒绝第二个. |

```ts
import { GlobPattern } from "@effected/glob";
import { Effect } from "effect";

Effect.runPromise(Effect.result(GlobPattern.compile("a".repeat(70_000)))).then(console.log);
// Failure with GlobPatternError:
// { reason: "PatternTooLong", limit: 65536, actual: 70000, pattern: "aaaa…" }
```

## 敌对投入

相配仍为多名相配,而包并不约束其全部工作. 四个衡量案例:

| 图案 | 候选人 | 时间 |
| --- | --- | --- |
| `**/a/**` | 50 000个部分 | 约3 s |
| `x` 和1 600个x `!(a)` (6.4 KB) (中文(简体) ) | `x` 和1 600个x `b` | 约25毫秒 |
| `*(a|?)` × 10,000 (60 KB) | 1 000 × 个 `a` | 约15毫秒 |
| `x!(a)` × 1 000个 | `xb` × 1 000 (2,000个字符) | 约 1.6 s, 长度约为立方体( 22 ms at 400 字符); 小型匹配 11 仍然较慢 |

Brace 扩展在默认情况下,将编译和匹配工作乘以其选项 `braceExpandMax` 100,000;数值范围为100或100多的数值不扩展。 匹配是同步的,并屏蔽调用线程直到返回,所以进程内超时无法阻止它: `Effect.timeout` 周围 `Effect.sync(() => pattern.matches(path))` 仍然等待整个比赛。 当模式或路径来自不可信输入时,在匹配前绑定输入:

-   限制图案的长度,以及图案可能来自何处;
-   限制候选人的长度或部分数;
-   下调 `braceExpandMax`: 与 `GlobPatternOptions.make({ braceExpandMax: 100 })` 诸如: `**/a/**/*{a,b}{a,b}{a,b}{a,b}{a,b}{a,b}{a,b}{a,b}{a,b}{a,b}*` (1,024个替代品) 编译失败 `ExpansionBudgetExceeded`。 。 。 .

A 类 `GlobSet` 是一个编译: 其成员共享一个编译预算, 而通过该集键入失败 `CompileBudgetExceeded`. 部分验证正则exp每部分收取一次,其中每个Unicode财产收取1 536个单位(`[[:alpha:]]` 有两个, `[[:word:]]` 4): 共用一个部分的行,例如: `d1/[[:alpha:]]*.ts` 财务报告和审定财务报表 `d2/[[:alpha:]]*.ts`,以20,000行编译,而每行都有自己的一套 `[[:alpha:]]` 大约2 550行(约1 280行) `[[:word:]]`) (中文(简体) ). 平面线、支架线和数值线组编成2万行.

A 类 `GlobSet`除外情形是:a `!` 线条可以删除它所坐位置的匹配内容,而以后不再放回路径。 没有 `workspaces` 否定是命令,所以 `["packages/*", "!packages/a", "packages/a"]` 保留 `packages/a` 在那里,并把它在这里.

在需要截止时间时,从调用线上执行:在截止时间过后终止的工人中运行匹配,在子程序中运行,或在主机自己请求的截止时间下运行.

`maxGlobstarRecursion` 以 1000 为界,所以默认节点堆栈上没有被接受的值溢出。 如果一个打电话的人跑了 `matches` 堆放量比这要少 堆放量从不丢出: `matches` 答案似乎没有匹配的替代方案,即 `false` 用于普通模式和 `true` 对于一个被否定的。 这并不总是复发盖对有几种替代品的套接字模式的答案,因为套接字仅能使套接字短路而引擎继续尝试其余部分,而整个套接字模式的外出答案.

## 通关卡

`Wildcard` 是一个单独的匹配器,用于图案 `agent:*` 在许可列表中。 这不是普通的方言: `*` 匹配除白空间以外的任意字符, `?` 匹配一个字符而不是白空间,而其他字符都是字面的。 没有分隔器,所以 `*` 横跨 `/`,以及 `[`, (中文(简体) ), `{`, (中文(简体) ), `!`, (中文(简体) ), `\` 和领先者 `.` 没什么特别的.

```ts
import { Wildcard, WildcardOptions } from "@effected/glob";

const isAgent = Wildcard.compile("agent:*");
console.log(isAgent("agent:okfit/claude-code"), isAgent("agent: x"));
// true false

console.log(Wildcard.matches("HUMAN:*", "human:spencer", WildcardOptions.make({ nocase: true })));
// true
```

`nocase` 比较 Unicode 简单大小写折叠下的正则表达式 `i` 财务报告和审定财务报表 `u` 旗帜是。 字符是代码点,白空间是什么 `\s` 匹配 `u` 旗帜。 编译和匹配从不掷出. 相配不倒行走,因此最多要花图案的长度乘以被选手,相接的恒星倒塌为一.

## 特征

-   `GlobPattern.compile(source, options?)` —— 说 `Effect<GlobPattern, GlobPatternError>`;相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相相去相去相去相去相去相去相相去相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.
-   `GlobPattern#matches(candidate)` ——总,纯,无出错频道.
-   `GlobPattern#hasMagic` 编号 : `negated` 编号 : `enumerationPrefix` 编号 : `crossesSegments` ——目录统计器元数据. `crossesSegments` 由前缀测量每个套接字的替代股票,所以 `{apps,packages}/*` (前缀) `""`) 横分.
-   `GlobPattern.alternativeCount(source, options?)` —— 说 `Result<number, GlobPatternError>`: 编译匹配的选项, 不编译即可计数( e) :`{a,b}/{c,d}` 是 4; 数值范围为 100 个或以上的数值为 1。 被扩建队的警卫包围,通过 `braceExpandMax` 在自己的天花板上阻止它.
-   `GlobPattern#literalPrefix` ——第一个魔法段前的字面主要目录片段,没有被逃脱,没有后遗症的斜线(`src/{a,b}/*.ts` 给 `src`· ; `src/a.ts` 给予自己; `""` 当第一部分是魔术的时候。 括号不扩展:未脱逃 `{` 这是魔法.
-   `extglobBang` 选项 - 读取线索 `!(` 作为 `!(…)` 而不是像皮克赛那样完全否定 默认关闭,所以小匹配的读取持有; `!a` 仍然否定。 仅此点对等比对( set) `dot` 也同意维特. `nonegate: true` 也给皮克的答案 `!(`,但禁用每个 `!` 否定. `GlobSet` 表面没有选项, 带一条线索 `!` 本身作为排除标记.
-   `GlobPattern.escape(literal)` 编号 : `unescape(pattern)` ——从用户提供文字中安全地构建图案.
-   `GlobPattern.FromString` a 包括: `Schema.Codec<GlobPattern, string>` 用于在配置图案中嵌入图案.
-   `GlobPatternOptions` —— 完整的微型匹配选项表面, 计划验证. 选项精细匹配; 它们从来不承认默认拒绝的模式 .
-   `maxGlobstarRecursion` 选项——从 `1` 改为 `1000`默认值 `200`;走过它是一个虚假的负数,永远不会出错.
-   `Wildcard.compile(pattern, options?)` 编号 : `Wildcard.matches(pattern, candidate, options?)` —— 说 `*` 财务报告和审定财务报表 `?` 只有,没有分隔语义; `WildcardOptions` 携带 `nocase`。 。 。 .
-   `GlobSet.compile(patterns)` - 包括/不包括装有 `literals`, (中文(简体) ), `wildcards` 财务报告和审定财务报表 `excludes` 访问者加 `isExcluded`。 。 。 .
-   `GlobPatternError` —— 说 `_tag`\-可流体,携带 `pattern`, (中文(简体) ), `reason`, (中文(简体) ), `limit` 财务报告和审定财务报表 `actual`。 。 。 .

## 归属

发动机在 `src/internal/` 端口带有以下属性:

-   [小型匹配](https://github.com/isaacs/minimatch) 10.2.5,行为为11.0.5 — Isaaac Z. Schlueter和贡献者 BlueOak-1.0.0
-   [@isaacs/ 不可重复的- glob- match](https://github.com/isaacs/nonrecursive-glob-match) 1.1.0,部分配对小赛 11.0.5跑出——以撒Z. Schlueter和Contrifors, BlueOak-1.0.0
-   [收缩-扩展](https://github.com/juliangruber/brace-expansion) 5.0.12 — Julian Gruber,麻省理工学院
-   [平衡匹配](https://github.com/juliangruber/balanced-match) 4.0.4 — 麻省理工学院朱利安·格鲁伯

每个端口文件都携带了它的通知,而真实的微型匹配被作为这个包套件中的测试甲骨文.

## 许可证

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

## 常见问题

### @effected/glob 是什么？

全真格来比作"效应"计划:完全的相配方言被编译为纯弦上游\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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