---
title: "Worktrees"
description: "基于 Cursor 官方 Worktrees 文档解释 Agents Window worktrees、.cursor/worktrees.json、清理和 /worktree /best-of-n。"
verifiedAt: "2026-05-09"
---

Worktrees（git worktree，把同一仓库 checkout 到多个独立目录的原生 git 能力）让 Agent 在隔离的 Git checkout 里工作。官方文档说明：每个任务都有自己的 files、dependencies 和 changes，你的 main checkout 不会被碰到。

> [!NOTE]
> **阅读目标**：读完本章，你应该能判断什么时候必须用 worktree，并能配置 `.cursor/worktrees.json`、清理策略和 Editor Window 中的 `/worktree` / `/best-of-n`。

## 1. 先看入口边界

官方页面先给了一个关键边界：

| 位置 | 怎么用 worktree |
| --- | --- |
| Agents Window | UI-native worktrees，只在 Agents Window 可用 |
| Editor Window | 使用 Worktree Skills commands，例如 `/worktree`、`/best-of-n` |
| Cursor CLI | 可以读取 `.cursor/worktrees.json` 的 setup 配置 |

所以不要只问“Cursor 有没有 worktree”。要先看你处在哪个界面。

## 2. Worktree 解决什么

```mermaid
flowchart TD
  Main["Main checkout"] --> TaskA["Agent task A"]
  Main --> TaskB["Agent task B"]
  TaskA --> WTA["Worktree A"]
  TaskB --> WTB["Worktree B"]
  WTA --> ReviewA["Review / commit / PR A"]
  WTB --> ReviewB["Review / commit / PR B"]
  ReviewA --> MainDecision["Apply or merge intentionally"]
  ReviewB --> MainDecision
```

适合使用：

- 同一个 repo 上启动多个 agents。
- 风险重构，不想污染当前 checkout。
- 需要独立安装依赖、构建和测试。
- 想比较多个实现候选。
- 需要一个简单 cleanup path。

不适合省掉 review。Worktree 只是隔离，不是质量保证。最后仍然要看 diff、跑测试、决定 commit、PR 或 apply。

## 3. Agents Window 流程

官方说明：当你在 Agents Window 中把 agent 启动或移动到 worktree，Cursor 会为这个 agent 创建一个 separate checkout。任务在 worktree 里继续执行，变更不会进入 main checkout。

Agent 完成后，你可以：

- 在 Agents Window 中 review 结果。
- 继续在 worktree 里工作。
- 从这个 checkout 创建 commit 或 PR。
- 把结果带回 main workspace。

## 4. `.cursor/worktrees.json`

Cursor 会用 `.cursor/worktrees.json` 自定义 worktree setup。官方说明它会在这些地方创建 worktree 时检查该文件：Agents Window、Editor Window、Cursor CLI。

查找顺序：

1. worktree path。
2. project root path。

配置支持三个 setup key：

| Key | 用途 |
| --- | --- |
| `setup-worktree-unix` | macOS / Linux 命令或脚本路径，优先于 generic fallback |
| `setup-worktree-windows` | Windows 命令或脚本路径，优先于 generic fallback |
| `setup-worktree` | 所有系统的通用 fallback |

每个 key 可以是 command array，也可以是相对 `.cursor/worktrees.json` 的 script filepath。

```json
{
  "setup-worktree-unix": [
    "pnpm install",
    "cp $ROOT_WORKTREE_PATH/.env.local .env.local",
    "pnpm run build"
  ],
  "setup-worktree-windows": [
    "pnpm install",
    "copy %ROOT_WORKTREE_PATH%\\.env.local .env.local"
  ]
}
```

官方提醒：不建议把 dependencies symlink 到 worktree。这样可能影响 main worktree。更好的做法是用 fast package manager，例如 `bun`、`pnpm` 或 `uv`。

<details>
<summary>深读：为什么 setup 里复制 env 要谨慎</summary>

官方示例会复制 `.env` 或 `.env.local`，因为很多项目离开环境变量无法启动。但真实团队不能盲目把密钥复制到每个 worktree。

建议把可复制的本地开发 env 和生产密钥分开；worktree setup 只复制开发必需、可回收、低风险的配置。涉及客户数据、生产 token、付款后台 key 的文件不要自动扩散。
</details>

## 5. 调试和清理

如果 worktree setup 失败，官方建议打开 editor 的 Output panel，选择 `Worktrees Setup`。

Cursor 也可以自动清理旧 worktrees，减少磁盘占用。

```json
{
  "cursor.worktreeCleanupIntervalHours": 6,
  "cursor.worktreeMaxCount": 20
}
```

| 设置 | 含义 |
| --- | --- |
| `cursor.worktreeCleanupIntervalHours` | 多久检查一次旧 worktrees |
| `cursor.worktreeMaxCount` | 超过多少个 worktrees 后清理旧项 |

## 6. Editor Window 命令

Editor Window 中，用 Worktree Skills commands。

| 命令 | 作用 |
| --- | --- |
| `/worktree` | 在独立 checkout 中完成当前 chat 后续任务 |
| `/apply-worktree` | 把 worktree 里的结果带回 main checkout 测试 |
| `/delete-worktree` | 完成后删除隔离 checkout |
| `/best-of-n` | 让多个模型用同一 prompt 并行产出候选 |

示例：

```text
/worktree fix the failing auth tests and update the login copy
```

`/best-of-n` 会让每个候选 run 拿到自己的 worktree。它只负责比较 runs，不会自动 merge 回 main checkout。选出结果后，你可以在 worktree 中 commit/push，或用 `/apply-worktree` 带回 main。

## 7. 验收清单

Worktree 任务完成后检查：

- `git worktree list` 能看清当前 worktrees。
- 每个任务有独立目标和验收方式。
- setup 过程没有复制不该扩散的密钥。
- 依赖安装、build、test 都在 worktree 内完成。
- diff 只包含该任务需要的文件。
- 选中候选后才 apply、commit、push 或 open PR。
- 旧 worktree 有清理策略。

## 本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. Agents Window 和 Editor Window 使用 worktrees 的入口有什么区别？
2. `.cursor/worktrees.json` 的三个 setup key 分别解决什么问题？
3. `/best-of-n` 为什么不能代替人工 review 和 merge？

通过标准：你能为一个多 Agent 并行任务设计 worktree 隔离、setup、验证和清理策略。

## 官方来源

- [Cursor Worktrees](https://cursor.com/docs/configuration/worktrees.md) —— 官方说明 Agents Window worktrees、setup 配置、cleanup、Editor Window commands 和 `/best-of-n`。
- [Cursor CLI Worktrees](https://cursor.com/docs/cli/using.md#cli-worktrees) —— 官方说明 CLI worktree 入口。

## 接下来去哪

<Cards>
  <Card title="Agent 安全边界" description="并行和自动化前，继续看 Agent 默认权限。" href="/docs/cursor/official/01-agent-workflow/21-agent-security" />
  <Card title="Agents Window" description="回到并行 Agent 的主界面说明。" href="/docs/cursor/official/01-agent-workflow/11-agents-window" />
</Cards>
