> ## 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.

# 工作空间

> 使用多个独立包开发复杂的单体仓库

Bun 支持 `package.json` 中的 [`workspaces`](https://docs.npmjs.com/cli/v9/using-npm/workspaces?v=true#description)。使用工作空间，你可以在一个仓库中开发多个独立的包，即\_单体仓库（monorepo）\_。

单体仓库通常具有以下结构：

```txt File Tree icon="folder-tree" theme={null}
<根目录>
├── README.md
├── bun.lock
├── package.json
├── tsconfig.json
└── packages
    ├── pkg-a
    │   ├── index.ts
    │   ├── package.json
    │   └── tsconfig.json
    ├── pkg-b
    │   ├── index.ts
    │   ├── package.json
    │   └── tsconfig.json
    └── pkg-c
        ├── index.ts
        ├── package.json
        └── tsconfig.json
```

根 `package.json` 中的 `"workspaces"` 键列出了要视为工作空间的子目录。按照惯例，它们位于名为 `packages` 的目录中。

```json package.json icon="file-json" theme={null}
{
  "name": "my-project",
  "version": "1.0.0",
  "workspaces": ["packages/*"],
  "devDependencies": {
    "example-package-in-monorepo": "workspace:*"
  }
}
```

<Note>
  **Glob 支持** — Bun 在 `"workspaces"` 中支持完整的 glob 语法，包括否定模式如 `!**/excluded/**`。请参阅[支持的 glob 模式](/runtime/glob#supported-glob-patterns)。
</Note>

```json package.json icon="file-json" theme={null}
{
  "name": "my-project",
  "version": "1.0.0",
  "workspaces": ["packages/**", "!packages/**/test/**", "!packages/**/template/**"]
}
```

每个工作空间都有自己的 `package.json`。要引用单体仓库中的另一个包，请使用 semver 范围或工作空间协议（例如 `workspace:*`）作为 `package.json` 中的版本。

```json packages/pkg-a/package.json icon="file-json" theme={null}
{
  "name": "pkg-a",
  "version": "1.0.0",
  "dependencies": {
    "pkg-b": "workspace:*"
  }
}
```

`bun install` 会安装单体仓库中所有工作空间的依赖，并在可能的情况下进行去重。要仅为特定工作空间安装依赖，请使用 `--filter` 标志。

```bash theme={null}
# 为所有以 `pkg-` 开头的工作空间安装依赖，排除 `pkg-c`
bun install --filter "pkg-*" --filter "!pkg-c"

# 也可以使用路径。这等同于上面的命令。
bun install --filter "./packages/pkg-*" --filter "!pkg-c" # 或 --filter "!./packages/pkg-c"
```

发布时，Bun 会将 `workspace:` 版本替换为包的 `package.json` 版本：

```
"workspace:*" -> "1.0.1"
"workspace:^" -> "^1.0.1"
"workspace:~" -> "~1.0.1"
```

特定版本会优先于包的 `package.json` 版本：

```
"workspace:1.0.2" -> "1.0.2" // 即使当前版本是 1.0.1
```

工作空间有几个主要优势。

* **代码可以拆分为逻辑部分。** 如果一个包依赖于另一个包，将其作为依赖添加到 `package.json` 中。如果包 `b` 依赖于 `a`，`bun install` 会将本地的 `packages/a` 目录安装到 `node_modules` 中，而不是从 npm 注册表下载。
* **依赖可以去重。** 如果 `a` 和 `b` 共享一个公共依赖，它会被\_提升\_到根 `node_modules` 目录。这节省了磁盘空间，并最大限度地减少了多个版本的包同时安装导致的"依赖地狱"。
* **在多个包中运行脚本。** 使用 [`--filter` 标志](/pm/filter)同时在多个包中运行 `package.json` 脚本，或使用 `--workspaces` 在所有工作空间中运行脚本。

## 使用 Catalogs 共享版本

当许多包需要相同的依赖版本时，在根 `package.json` 的目录中统一定义这些版本，并使用 `catalog:` 协议从工作空间中引用它们。更新目录会更新引用它的所有包。请参阅 [Catalogs](/pm/catalogs)。

<Note>
  ⚡️ **速度** — 即使对于大型单体仓库，安装也很快。Bun 在 Linux 上安装 [Remix](https://github.com/remix-run/remix) 单体仓库大约需要 `500ms`。

  * 比 `npm install` 快 28 倍
  * 比 `yarn install` (v1) 快 12 倍
  * 比 `pnpm install` 快 8 倍

  <Image src="https://user-images.githubusercontent.com/709451/212829600-77df9544-7c9f-4d8d-a984-b2cd0fd2aa52.png" />
</Note>