---
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="/zh-Hant/docs/cursor/official/01-agent-workflow/21-agent-security" />
  <Card title="Agents Window" description="回到並行 Agent 的主介面說明。" href="/zh-Hant/docs/cursor/official/01-agent-workflow/11-agents-window" />
</Cards>
