> ## Documentation Index
> Fetch the complete documentation index at: https://bun.ll1025.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Glob（文件匹配）

> 使用 Bun 快速的原生文件通配实现

## 快速入门

**扫描目录中匹配 `*.ts` 的文件**：

```ts theme={null}
import { Glob } from "bun";

const glob = new Glob("**/*.ts");

// 扫描当前工作目录及其所有子目录（递归）
for await (const file of glob.scan(".")) {
  console.log(file); // => "index.ts"
}
```

**将字符串与 glob 模式匹配**：

```ts theme={null}
import { Glob } from "bun";

const glob = new Glob("*.ts");

glob.match("index.ts"); // => true
glob.match("index.js"); // => false
```

`Glob` 类实现了以下接口：

```ts theme={null}
class Glob {
  scan(root: string | ScanOptions): AsyncIterable<string>;
  scanSync(root: string | ScanOptions): Iterable<string>;

  match(path: string): boolean;
}

interface ScanOptions {
  /**
   * 开始匹配的根目录。默认为 `process.cwd()`
   */
  cwd?: string;

  /**
   * 允许模式匹配以点号（`.`）开头的条目。
   *
   * @default false
   */
  dot?: boolean;

  /**
   * 返回条目的绝对路径。
   *
   * @default false
   */
  absolute?: boolean;

  /**
   * 是否遍历符号链接目录的后代。
   *
   * @default false
   */
  followSymlinks?: boolean;

  /**
   * 符号链接损坏时是否抛出错误
   *
   * @default false
   */
  throwErrorOnBrokenSymlink?: boolean;

  /**
   * 仅返回文件。
   *
   * @default true
   */
  onlyFiles?: boolean;
}
```

## 支持的 Glob 模式

Bun 支持以下 glob 模式：

### `?` - 匹配任意单个字符

```ts theme={null}
const glob = new Glob("???.ts");
glob.match("foo.ts"); // => true
glob.match("foobar.ts"); // => false
```

### `*` - 匹配零个或多个字符，不包括路径分隔符（`/` 或 `\`）

```ts theme={null}
const glob = new Glob("*.ts");
glob.match("index.ts"); // => true
glob.match("src/index.ts"); // => false
```

### `**` - 匹配包括 `/` 在内的任意数量字符

```ts theme={null}
const glob = new Glob("**/*.ts");
glob.match("index.ts"); // => true
glob.match("src/index.ts"); // => true
glob.match("src/index.js"); // => false
```

### `[ab]` - 匹配方括号内的一个字符，也支持字符范围

```ts theme={null}
const glob = new Glob("ba[rz].ts");
glob.match("bar.ts"); // => true
glob.match("baz.ts"); // => true
glob.match("bat.ts"); // => false
```

可以使用字符范围（例如 `[0-9]`、`[a-z]`）和否定运算符 `^` 或 `!` 来匹配方括号内字符**之外**的任何内容（例如 `[^ab]`、`[!a-z]`）。

```ts theme={null}
const glob = new Glob("ba[a-z][0-9][^4-9].ts");
glob.match("bar01.ts"); // => true
glob.match("baz83.ts"); // => true
glob.match("bat22.ts"); // => true
glob.match("bat24.ts"); // => false
glob.match("ba0a8.ts"); // => false
```

### `{a,b,c}` - 匹配任意一种给定的模式

```ts theme={null}
const glob = new Glob("{a,b,c}.ts");
glob.match("a.ts"); // => true
glob.match("b.ts"); // => true
glob.match("c.ts"); // => true
glob.match("d.ts"); // => false
```

这些模式可以嵌套最多 10 层，并包含前述的任何通配符。

### `!` - 在模式开头否定结果

```ts theme={null}
const glob = new Glob("!index.ts");
glob.match("index.ts"); // => false
glob.match("foo.ts"); // => true
```

### `\` - 转义上述任何特殊字符

```ts theme={null}
const glob = new Glob("\\!index.ts");
glob.match("!index.ts"); // => true
glob.match("index.ts"); // => false
```

## Node.js `fs.glob()` 兼容性

Bun 还实现了 Node.js 的 `fs.glob()` 函数，并附加了更多功能：

```ts theme={null}
import { glob, globSync, promises } from "node:fs";

// 模式数组
const files = await promises.glob(["**/*.ts", "**/*.js"]);

// 排除模式
const filtered = await promises.glob("**/*", {
  exclude: ["node_modules/**", "*.test.*"],
});
```

所有三个函数（`fs.glob()`、`fs.globSync()`、`fs.promises.glob()`）都支持：

* 模式数组作为第一个参数
* 用于过滤结果的 `exclude` 选项