Git Worktree 完全指南：并行开发、多分支管理的终极解决方案

发布于 2026年03月23日 08:30

#Git#CLI

在日常开发中，我们经常会遇到这样的场景：

• 正在开发一个大功能
• 突然线上出现 Bug 需要紧急修复
• 或者同时需要维护多个版本
• 又或者要 review PR / 对比两个分支

传统做法是：

git stash
git checkout other-branch
...
git checkout back
git stash pop

频繁切分支不仅低效，而且 非常容易出错。

其实 Git 早就提供了一个非常强大的功能：

git worktree —— 一个仓库同时打开多个分支开发

本文将带你从 0 → 高手级 掌握它。

一、什么是 git worktree

git worktree 允许你：

在同一个 Git 仓库中创建多个工作目录（working directory）

每个目录：

• 对应一个分支
• 可以同时开发
• 共享 Git 对象库（几乎不占空间）

例如：

project-main/        → main 分支
project-feature/     → feature 分支
project-hotfix/      → hotfix 分支

你可以：

可以同时打开 3 个 IDE 窗口开发。

这在大型项目中极其高效。

二、为什么需要 git worktree

避免频繁切分支

传统开发：

开发 feature → 切 main 修 bug → 再切回来

问题：

• 容易忘记 stash
• 容易污染工作区
• 编译缓存被破坏
• 模拟器 / 环境需要重启

worktree 方案：

feature 在一个目录
hotfix 在另一个目录

互不影响。

同时运行多个版本 App

移动端非常常见：

• 一个分支：Flutter 3
• 一个分支：Flutter 4
• 一个分支：线上版本

你可以：

• 同时运行多个模拟器
• 做 UI 对比
• 做性能测试

这在架构升级期极其重要。

PR Review 神器

review 别人代码时：

git worktree add ../review pr-123

优点：

• 不污染当前开发环境
• 可以单独 build / run
• 可以调试

review 体验直接提升一个等级。

三、基本使用方式

查看当前 worktree

git worktree list

输出类似：

/repo-main       [main]
/repo-featureA   [feature/A]

创建 worktree

创建已有分支

git worktree add ../repo-feature feature/A

创建新分支

git worktree add -b feature/B ../repo-featureB

Git 会：

• 创建目录
• 创建分支
• 自动 checkout

删除 worktree（正确方式）

git worktree remove ../repo-feature

不要直接：

rm -rf

否则会留下 幽灵 worktree（后面讲）。

四、底层原理（非常重要）

创建 worktree 后：

.git/
 ├── objects
 ├── refs
 └── worktrees/
       ├── repo-feature
       └── repo-hotfix

每个 worktree：

• 有独立 HEAD
• 有独立 index
• 有独立 working directory

但：

所有 worktree 共享 object database

因此：

• 创建速度极快
• 不需要 clone
• 几乎不占磁盘

本质是：

一个仓库的多个“视图”

五、git worktree prune（很多人不懂）

如果你手动删除目录：

rm -rf ../repo-feature

Git 不知道目录没了。

执行：

git worktree list

可能看到：

../repo-feature (gone)

这叫：

stale worktree（幽灵 worktree）

这时需要：

git worktree prune

作用：

• 清理 .git/worktrees 中失效记录
• 修复 branch already checked out 等错误

警告：使用 --expire 选项前，务必确认：

• 没有未提交的重要更改
• 分支已推送到远程

建议按以下步骤操作：

git worktree list              # 先确认哪些是 (gone)
git worktree prune             # 默认 prune 足够
# git worktree prune --expire now  # 确认无误后再执行

六、重要限制（必须知道）

一个分支不能同时在多个 worktree checkout

否则：

fatal: 'main' is already checked out

原因：

• HEAD 会冲突
• index 会冲突

解决：

checkout 新分支

submodule 项目更容易出问题

如果：

• worktree 移动目录
• CI 清理异常

可能需要：

git worktree prune
git submodule sync

七、高手级最佳实践（推荐）

建立长期 worktree 结构

例如：

repo/
repo-develop/
repo-release/
repo-hotfix/

长期存在：

• develop：日常开发
• release：测试版本
• hotfix：线上修复

注意事项：

• 长期 worktree 需要手动 git pull 更新
• 适合同一分支频繁切换的固定工作流
• 多分支并行开发建议使用临时 worktree

这是一种非常成熟的 大型项目 Git 结构设计。

用于 CI / CD

适用场景：

• 自建 Jenkins / GitLab Runner（非容器化）
• 单机多分支构建需求
• 需要保留编译缓存的场景

不适用场景：

• 容器化 CI（GitHub Actions、GitLab CI、CircleCI）- 每次都是新环境
• 多机分布式构建 - worktree 无法跨机器共享

例如 Mac Mini 构建机：

• 每个分支一个 worktree
• Jenkins 不需要反复 checkout

可以显著减少：

• 构建时间
• 磁盘 IO
• 编译缓存丢失

八、总结

git worktree 是 Git 最被低估的高级功能之一

它能带来的收益：

• 并行开发多个分支
• 提升 PR review 效率
• 支持多版本同时运行
• 降低切分支风险
• 减少 CI 构建成本

一句话理解：

worktree = 在一个仓库中同时打开多个分支开发环境