当前位置：首页 » AI编程开发

Claude Code Worktree 使用指南：多分支并行开发效率翻倍

3小时前 AI编程开发 16 0

Worktree 是 Claude Code 团队每天都在用的功能，Anthropic 负责人 Boris Cherny 称它为"排名第一的生产力技巧"。其主要作用是让多个 Agent 能够并行工作而不互相干扰。

Worktree 本是 Git 的原生功能，Claude Code 的 --worktree 命令将这个功能封装得更加简单易用，一条命令就能创建隔离环境、启动 Claude 实例、完成后自动清理。

技术特点

共享数据库：Worktree 共享同一个 .git 数据库，所有提交历史、分支信息都是共享的。在一个 worktree 里创建的 commit，其他 worktree 立刻可见。
独立文件状态：每个 worktree 维护独立的文件状态，同时共享 git 历史记录，防止 Claude 实例在处理不同任务时相互干扰。
自动化管理：相比原生 Git Worktree，Claude Code 的 --worktree 命令封装了复杂流程，能自动创建隔离环境、启动 Claude 实例，并在任务完成后自动清理。

使用场景

日常使用 Claude Code 的开发模式是以文件目录为工作区，使用 Git 进行版本控制，这意味着工作区每次只能有一个工作分支。如果启用多个 Claude Code 窗口进行开发会导致代码冲突。Worktree 可以很好地处理这种场景。

苏米注：Worktree 并非万能，小任务上使用反而浪费时间，因为需要经历创建环境、安装依赖、开发、合并等过程，可能比任务本身耗时还久。

Worktree 更适合以下使用场景：

功能解耦：当你有多个互不相关的 Feature 或 Bug 需要同时开发/修复时。
长时任务托管：对于需要运行很久的任务（如大规模重构或跑大型测试），可以开一个 Worktree 让 Claude 慢慢跑，不影响你在主目录继续写代码。
实验性改动：在完全隔离的环境中进行风险较高的尝试，即便写烂了也不会影响主分支的稳定性。

前置条件

在 Claude Code CLI 中使用 Worktree 需满足以下条件：

Git 初始化：必须在已初始化的 Git 仓库目录中
至少有一个 commit：空仓库无法创建 worktree
有远程默认分支：必须有远程默认分支，Claude Code CLI Worktree 默认从远程分支检出

基本使用

创建 Worktree

首先确保项目已经初始化过 Git，即项目中包含 .git 目录。

在命令行终端输入 git remote show origin 查看远程分支信息。

验证 Worktree 的默认迁出分支是否为默认远程分支。首先基于 main 分支创建一个 dev 分支，在本地 main 分支添加"branch main"标识。

在本地 dev 分支添加"branch dev"标识。

接着使用 --worktree 或 -w 参数启动 Claude Code CLI：

# 创建名为 "feat-home" 的 worktree 并启动 Claude
$ claude -w feat-home

# 自动生成随机名称（如 "curious-marinating-flamingo"）
$ claude -w

执行上面命令后，Claude Code 在工作区 .claude/worktrees 目录下创建了 2 个新的工作区目录。

打开 Worktree 工作区下的 README 文件，可以看到均是未做过修改的，可以排除 Worktree 的代码是从本地分支创建的。

让 AI 帮忙分析，AI 通过 git log、git merge-base 等信息确认：worktree 是基于 origin/main 创建的，而非当前分支。

在启动的 Claude Code CLI 中执行 !pwd 可以看到当前工作区目录已经变成了 Worktree 工作区目录。

Worktree 除了创建工作区目录，还创建了 Git 分支，在 Cursor 等 IDE 中可以直观看到。

Claude Code Worktree 执行的四件事

在 .claude/worktrees/ 目录下创建新的工作目录
创建名为 worktree- 的新分支
从远端默认分支（origin/main 或 origin/master）检出代码（不是你当前所在的分支）
在 Worktree 新目录中启动 Claude Code

从特定分支签出

Claude Code Worktree 默认从远端的默认分支签出代码。如果想从指定分支签出代码，可以通过 AI 创建或使用 Git 原生命令创建。

通过 AI 创建

首先在当前分支添加分支标识并提交（没有提交的内容从当前分支签出时无法同步签出）。

在当前 Claude Code CLI 会话中直接让 Claude Code 创建 Worktree：

基于当前分支创建一个新的 worktree

查看新创建的 Worktree 工作区中的 README 文件，包含上面添加的分支标识。

Git 原生命令创建

Claude Code CLI Worktree 是在 Git 原生命令基础上封装的，使用 Git 命令创建 Worktree 更强大。

切换到 dev 分支，在命令行终端执行如下命令基于当前分支创建 Worktree：

# 基于当前 HEAD 创建 worktree
$ git worktree add -b test-feature .claude/worktrees/test-feature HEAD

创建完成后和 Claude Code Worktree 创建的效果一致。

也可以基于特定的分支创建 Worktree：

# 基于某个特定分支
$ git worktree add -b hotfix-home .claude/worktrees/hotfix-home origin/develop

使用 Git 命令创建的 Worktree，可以进入到 Worktree 工作目录启动 Claude Code CLI：

$ cd .claude/worktrees/test-feature
$ claude

或者直接使用 --worktree 参数启动，Claude Code CLI 会自动打开对应工作区：

$ claude --worktree test-feature

退出与清理

从 Worktree 中退出时，Claude Code CLI 会提示选择保留或删除。

Keep worktree：保留 Worktree
Remove worktree：删除 Worktree 及所有文件更改、Commit

踩坑记录：需要保留下次继续使用时一定要选【Keep worktree】，否则所有更改都会丢失。

重新启用已存在的 Worktree 时，可以直接通过下面命令启动：

$ claude -w feat-home

代码合并

使用 Claude Code Worktree 开发并验证完成后，下一步是把改动合并到主分支。可以通过 AI 合并和手动合并两种方式完成。

通过 AI 合并（推荐）

首先提交修改内容。

在 Claude Code CLI 会话中：

把 worktree-test-feature 分支改动合并到当前分支

如果 worktree 中某些不想要的 commit，可以选择性地 cherry-pick：

查看 worktree-test-feature 分支所有 commit 历史，把修改 README 的 commit cherry-pick 到当前分支

示例中修改了 dev 和 worktree-test-feature 中的 README 文件，合并时会出现冲突。只需告诉 AI 合并规则（如"保留双方更改"），也可以在 IDE 中手动合并。

合并完成后，Claude Code 同时清理了 test-feature Worktree 工作目录和分支。

手动合并

直接在命令行终端输入命令进行合并：

$ git merge feat-new-feature

或者在 IDE 中选择【分支】【合并】。

与通过 AI 合并方式不同的是，手动合并后 Claude Code CLI 不会自动清理 Worktree 和分支，需要手动清理：

使用如下命令清除 Worktree：

$ git worktree remove .claude/worktrees/feat-new-feature

Hooks

Claude Code Worktree 提供了 Worktree Hooks，通过定义工作区钩子，非 Git 用户也能完整体验到代码隔离机制带来的优势。

配置文件位置：.claude/settings.json

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "INPUT=$(cat); WORKTREE_PATH=$(echo \"$INPUT\" | jq -r '.cwd'); echo \"$WORKTREE_PATH\"; echo \"[$(date '+%Y-%m-%d %H:%M:%S')] WorktreeCreate: $(echo \"$INPUT\" | jq -r '.name')\" >> ~/.claude/worktree.log"
          }
        ]
      }
    ],
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "INPUT=$(cat); WORKTREE_PATH=$(echo \"$INPUT\" | jq -r '.worktree_path'); echo \"[$(date '+%Y-%m-%d %H:%M:%S')] WorktreeRemove: $WORKTREE_PATH\" >> ~/.claude/worktree.log"
          }
        ]
      }
    ]
  }
}

注意事项

worktree 删除失败

Worktree 没有被删除时分支是不能被删除的。

需要手动使用 Git 命令删除 Worktree：

$ git worktree remove .claude/worktrees/feat-new-feature

删除完成后即可删除分支。

创建进程卡死

如果出现无法创建 Worktree 进程卡死的情况，可以检查是否配置科学上网环境。

在命令行终端执行下面命令：

$ export https_proxy=http://127.0.0.1:7897 http_proxy=http://127.0.0.1:7897

重新执行即可。

苏米注：Worktree 是提升多任务并行开发效率的利器，但使用前务必确认满足前置条件，尤其是远程默认分支的存在。对于小型任务，直接使用 Git 分支可能更高效。

声明：本站原创文章文字版权归本站所有，转载务必注明作者和出处；本站转载文章仅仅代表原作者观点，不代表本站立场，图文版权归原作者所有。如有侵权，请联系我们删除。

未经允许不得转载：Claude Code Worktree 使用指南：多分支并行开发效率翻倍

请登录后发表评论