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

# bun --filter

> 使用 --filter 标志在 monorepo 中按模式选择包

`--filter`（或 `-F`）标志用于在 monorepo 中按模式选择包。模式可以用于匹配包名或包路径，支持完整的全局匹配语法。

目前 `--filter` 被 `bun install` 和 `bun outdated` 支持，也可以用来一次运行多个包的脚本。

***

## 匹配

### 包名 `--filter <pattern>`

名称模式基于 `package.json` 中指定的包名选择包。例如，如果你有包 `pkg-a`、`pkg-b` 和 `other`，你可以使用 `*` 匹配所有包，使用 `pkg*` 仅匹配 `pkg-a` 和 `pkg-b`，还可以通过完整包名匹配特定包。

### 包路径 `--filter ./<glob>`

路径模式以 `./` 开头来指定，将选择所有匹配该模式的目录中的包。例如，要匹配 `packages` 目录下所有子目录中的包，可以使用 `--filter './packages/**'`。要匹配位于 `packages/foo` 的包，则使用 `--filter ./packages/foo`。

***

## `bun install` 和 `bun outdated`

`bun install` 和 `bun outdated` 都支持 `--filter` 标志。

`bun install` 默认会为 monorepo 中所有包安装依赖。要为特定包安装依赖，可以使用 `--filter`。

假设一个 monorepo，工作区有 `./packages` 下的 `pkg-a`、`pkg-b` 和 `pkg-c`：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 安装除 `pkg-c` 以外所有工作区的依赖
bun install --filter '!pkg-c'

# 安装 `./packages` 目录下的包（`pkg-a`、`pkg-b`、`pkg-c`）的依赖
bun install --filter './packages/*'

# 与上面相同，但排除根目录 package.json
bun install --filter '!./' --filter './packages/*'
```

类似地，`bun outdated` 会显示 monorepo 中所有包的过期依赖，`--filter` 可以限制命令只作用于部分包：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 显示名称以 `pkg-` 开头的工作区的过期依赖
bun outdated --filter 'pkg-*'

# 仅显示根目录 package.json 的过期依赖
bun outdated --filter './'
```

有关以上命令的更多信息，请参见 [`bun install`](/pm/cli/install) 和 [`bun outdated`](/pm/cli/outdated)。

***

## 使用 `--filter` 运行脚本

使用 `--filter` 标志可以一次在多个包中执行脚本：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun --filter <pattern> <script>
```

假设你有一个 monorepo，包含两个包：`packages/api` 和 `packages/frontend`，它们都带有一个会启动本地开发服务器的 `dev` 脚本。通常你需要打开两个终端标签页，进入每个包目录分别运行 `bun dev`：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
cd packages/api
bun dev

# 在另一个终端
cd packages/frontend
bun dev
```

使用 `--filter`，你可以同时在这两个包中运行 `dev` 脚本：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun --filter '*' dev
```

两个命令将会并行运行，你会看到一个漂亮的终端界面显示各自的输出：

<Frame>![Terminal Output](https://github.com/oven-sh/bun/assets/48869301/2a103e42-9921-4c33-948f-a1ad6e6bac71)</Frame>

### 在工作区中运行脚本

过滤器会遵循你的[工作区配置](/pm/workspaces)：如果你的 `package.json` 指定了哪些包属于工作区，则 `--filter` 只会限制在这些包内。另外，在工作区中你可以使用 `--filter` 来运行位于任何地方的包中的脚本：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 包结构
# src/foo
# src/bar

# 在 src/bar 中：运行 src/foo 的 myscript，无需切换目录！
bun run --filter foo myscript
```

### 并行和顺序模式

结合 `--filter` 或 `--workspaces` 与 `--parallel` 或 `--sequential`，可以跨工作区包运行脚本，并带有 Foreman 风格的前缀输出：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 并发运行所有匹配包的 "build"
bun run --parallel --filter '*' build

# 顺序运行所有工作区包的 "build"
bun run --sequential --workspaces build

# 在所有包中运行符合通配符的脚本
bun run --parallel --filter '*' "build:*"

# 即使某个包的脚本失败，也继续运行其他脚本
bun run --parallel --no-exit-on-error --filter '*' test

# 在所有包中运行多个脚本
bun run --parallel --filter '*' build lint
```

每行输出前都会带有包名和脚本名的前缀（例如 `pkg-a:build | ...`）。如果没有使用 `--filter`/`--workspaces`，前缀仅是脚本名（例如 `build | ...`）。当包的 `package.json` 中没有 `name` 字段时，将使用相对于工作区根目录的路径代替。

使用 `--if-present` 与 `--workspaces` 一起，可跳过没有指定脚本的包，而不报错。

### 依赖顺序

Bun 在运行脚本时会尊重包的依赖顺序。假设你的工作区中包 `foo` 依赖包 `bar`，两者都带有 `build` 脚本。当你运行 `bun --filter '*' build`，你会发现 `foo` 只有在 `bar` 完成后才开始运行。