Claude Code worktree 怎麼用：多個會話並行開發不打架

本文根據 Claude Code 官方文檔《Run parallel sessions with worktrees》整理，核對日期 2026-10-07。worktree 需要 git 倉庫。

適用於誰

• 想讓一個 Claude Code 會話寫新功能、另一個同時修 bug，又擔心兩邊改同一批文件打架的人；
• 搜「claude code worktree 怎麼用」「claude code 並行任務」「worktree node_modules」的人；
• 想讓多個子代理並行改代碼、互不干擾的人。

結論先說

1. git worktree = 同一個倉庫的另一份獨立工作目錄：有自己的文件和分支，但共享同一個 .git 歷史和遠程。每個會話在自己的 worktree 裏改，互不影響。
2. 最簡單的用法：claude --worktree 名字（簡寫 -w），會在倉庫根目錄的 .claude/worktrees/名字/ 下新建 worktree，分支名為 worktree-名字。另開一個終端換個名字再來一次，就是第二個並行會話。
3. worktree 是一份全新的檢出：node_modules、.env 這些沒進 git 的東西都沒有。依賴要重新裝；.env 可以用 .worktreeinclude 自動複製。
4. 退出時，乾淨的 worktree 會自動刪除；有改動的會問你保留還是刪除——選刪除會連同分支和裏面的改動一起刪掉。
5. 建議把 .claude/worktrees/ 加進 .gitignore。

步驟

1. 在 worktree 裏啟動 Claude

bash
# 終端 1：做登入功能
claude --worktree feature-auth

# 終端 2：修一個 bug
claude --worktree bugfix-123

不寫名字的話，Claude 會自動起一個，比如 bright-running-fox。

注意：交互式運行要求這個目錄已被「信任」。如果從沒在這個倉庫裏運行過 claude，先運行一次普通的 claude 接受信任提示，否則 --worktree 會報錯退出。

也可以在會話裏直接說「在一個 worktree 裏做這件事」，Claude 會用 EnterWorktree 工具自己建一個。

2. 準備開發環境

worktree 裏只有被 git 跟蹤的文件。進去之後可以直接讓 Claude「先安裝依賴」，或者自己到 .claude/worktrees/名字/ 下運行項目的初始化命令（npm install、pip install -r requirements.txt 等）。

想把 .env 等被 gitignore 的文件自動帶進每個新 worktree，在項目根目錄建一個 .worktreeinclude，寫法同 .gitignore：

text
.env
.env.local
config/secrets.json

只有「匹配規則並且被 gitignore 的文件」才會複製，已跟蹤的文件不會重複。這個規則對 --worktree、子代理的 worktree 和桌面版的並行會話都生效。

3. 選擇從哪個分支開始

預設從遠程預設分支（通常是 main）新建，保證起點是乾淨的。如果你希望新 worktree 帶上當前本地的提交（比如讓子代理接着你沒推送的工作改），在設定裏寫：

json
{
  "worktree": {
    "baseRef": "head"
  }
}

baseRef 只接受 "fresh"（預設）和 "head" 兩個值，不能寫分支名。想從某個已有分支開始，用下面的「手動管理」。

基於某個 PR 開 worktree（審 PR、接手別人的改動很方便）：

bash
claude --worktree "#1234"

# 要加引號，不然 shell 會當成註釋。也可以直接傳 GitHub PR 或 GitLab MR 的連結，Claude Code 會從 origin 拉取該 PR 的提交，建在 .claude/worktrees/pr-1234。

4. 退出與清理

退出交互式 worktree 會話時，Claude 會檢查裏面有沒有會被刪除的工作（改動、未跟蹤文件、新提交）：

用 claude -p 非交互運行時沒有退出提示，worktree 不會被自動清理，需要自己 git worktree remove（被鎖時先 git worktree unlock）。

5. 讓子代理各自用一個 worktree

並行的子代理改同一批文件也會衝突。可以直接跟 Claude 說「讓你的子代理都用 worktree」，或者在自定義子代理裏固定寫上：

markdown
---
name: refactorer
description: 在很多文件裏執行機械式重構
isolation: worktree
---

在所有受影響的文件裏完成指定的重構，然後運行測試並彙報結果。

每個子代理拿到一個臨時 worktree，沒有改動就自動刪除，有改動的保留到之後的定期清理能安全刪除為止。批量大改動還可以用內置的 /batch 命令：它會把任務拆成 5～30 個獨立單元，每個單元在獨立 worktree 裏由一個後台子代理完成。

worktree 之間共享什麼

• .git 目錄：在 worktree 裏 git commit 寫的是同一個倉庫；
• 項目範圍的插件：主目錄裝過的，worktree 裏也能用，不用重裝；
• 權限批准：在 worktree 裏選「Yes, and don't ask again」，規則儲存到主目錄的 .claude/settings.local.json，所有 worktree 通用（Windows 等少數情況除外）；
• 未進 git 的技能、子代理、命令：如果 worktree 裏沒有 .claude/skills 等目錄，會讀主目錄的。

手動管理 worktree

需要從已有分支開始，或者想把 worktree 放到倉庫外面時，直接用 git：

bash
# 新分支
git worktree add ../project-feature-a -b feature-a

# 已有分支
git worktree add ../project-bugfix fix-issue-456

# 在裏面啟動 Claude
cd ../project-feature-a
claude

# 查看和刪除
git worktree list
git worktree remove ../project-feature-a

並行的幾種方式怎麼選

三者可以組合：多個會話各佔一個 worktree，會話裏再派子代理。

常見問題

Q：worktree 裏沒有 node_modules，每次都要重新裝嗎？

是的，worktree 是全新檢出，依賴要在裏面重新安裝（官方建議讓 Claude 裝，或者自己運行初始化命令）。同名 worktree 再次用 --worktree 名字 打開時會複用已有目錄，不必每次重裝。

Q：主目錄裏冒出一堆未跟蹤文件？

把 .claude/worktrees/ 加進 .gitignore。

Q：提示需要先信任工作區？

在倉庫目錄先運行一次普通的 claude，接受信任對話框，再用 --worktree。

Q：Hooks 裏的 $CLAUDE_PROJECT_DIR 會跟着進 worktree 嗎？

不會，它仍指向會話啟動時的項目根目錄。Hook 需要 worktree 路徑時，讀輸入 JSON 裏的 cwd 字段。

Q：不用 git（比如 SVN、Perforce）能用嗎？

預設的 worktree 依賴 git。其他版本控制系統可以配置 WorktreeCreate / WorktreeRemove Hook 替換創建和刪除邏輯，見官方文檔「Non-git version control」一節。

參考資料

• Run parallel sessions with worktrees（官方）：https://code.claude.com/docs/en/worktrees
• Run agents in parallel（官方）：https://code.claude.com/docs/en/agents
• Create custom subagents（官方）：https://code.claude.com/docs/en/sub-agents
• git worktree 文檔：https://git-scm.com/docs/git-worktree