如果你经常遇到这样的场景：正在 feature 分支开发到一半，线上突然报了个紧急 Bug，你不得不 git stash 一堆改动、切到 main、修 Bug、再切回来 stash pop……来回几次后状态全乱了，甚至代码冲突、改动丢失。

那么 git worktree 就是为彻底解决这个问题而生的。本文用大量实战场景，带你从零彻底搞懂它。

一、什么是 Git Worktree？

一句话：git worktree 让你把同一个仓库的不同分支，同时 checkout 到不同的目录里。

正常情况下，一个仓库只有一个"工作区"（working directory），你 git checkout 切分支，工作区里的文件就被替换。这意味着你同一时刻只能看到一个分支的内容。

而 worktree 打破了这个限制——你可以为仓库"克隆"出多个工作区，每个工作区 checkout 不同的分支，它们共享同一个 .git 仓库（共享所有 commit、对象、远程配置），但文件互不干扰。

打个比方：原来的 Git 就像"只有一个房间的房子"，你想看另一个分支（另一个人）就得让他先出去、换人进来。而 worktree 是"一栋楼里有多个房间"，每个房间住着一个分支，你可以随时推门进任何一个房间，互不打扰。

二、和 git clone / git stash / git submodule 的区别

很多人会问：我 git clone 一份、或者 git stash 不也行吗？它们的本质区别如下：

方式	是否共享 .git	磁盘占用	切换成本	典型场景
git checkout 切分支	共享	1 份	高（要 stash）	线性单一开发
git clone 多份	❌ 完全独立	N 份（大）	需手动 push/pull 同步	多机器/隔离环境
git stash	共享	1 份	易冲突/丢失	临时保存改动
git worktree	✅ 共享	仅多出工作文件	极低（秒切目录）	多分支并行开发
git submodule	独立子仓库	额外子目录	复杂（要更新引用）	引入第三方仓库

核心优势：worktree 既像 clone 一样能"同时拥有多个分支"，又像 checkout 一样"共享同一份仓库数据"，是性价比最高的并行开发方案。

三、核心命令速查

# 1. 创建一个新的 worktree（新目录 + 指定分支）
git worktree add <路径> <分支名>

# 2. 创建 worktree 的同时新建分支
git worktree add -b <新分支> <路径> [<基于的commit>]

# 3. 列出所有 worktree
git worktree list

# 4. 删除一个 worktree（删完后建议 prune）
git worktree remove <路径>
git worktree prune        # 清理已失效的 worktree 记录

# 5. 查看详细信息
git worktree list -v

记住这 5 条，下面的场景都是它们的组合应用。

四、场景实战（重点，建议跟着敲）

场景 1：开发到一半，紧急修复线上 Bug（最经典）

你在 feature/login 写了 200 行还没提交，线上 main 挂了。传统做法：stash → 切 main → 修 → 切回 → pop。用 worktree：

# 1. 不动当前分支！直接开一个新目录拉 main
git worktree add ../hotfix-bug main

# 2. 进入新目录，安心修 Bug
cd ../hotfix-bug
# ... 修改代码 ...
git add . && git commit -m "fix: 线上紧急Bug"
git push origin main

# 3. 修完删掉这个临时目录
cd ../my-project
git worktree remove ../hotfix-bug

关键点：你原来的 feature/login 那 200 行代码一个字都没动，完全不需要 stash。两个目录同时开着，用完即删。

场景 2：同时对比/测试两个分支

比如你想对比 v1.0 和 v2.0 的接口性能，或者本地同时跑新旧两个版本的前端：

git worktree add ../app-v1 v1.0
git worktree add ../app-v2 v2.0

# 现在两个目录同时存在，可以分别起服务对比
cd ../app-v1 && npm run dev   # 端口 3000
cd ../app-v2 && npm run dev   # 端口 3001

这比反复 checkout 切换方便太多，尤其适合做回归测试、A/B 对比、版本兼容性验证。

场景 3：长时间并行开发多个功能

同时推进 feature/auth、feature/payment、feature/dashboard 三个功能，每个都要几天：

git worktree add ../auth     feature/auth
git worktree add ../payment  feature/payment
git worktree add ../dashboard feature/dashboard

每个目录用独立的 IDE 窗口打开，上下文不切换、思路不中断。再也不用担心"切个分支回来忘了刚才写到哪"。

场景 4：跑长时间任务（编译/测试）时不阻塞主线

比如你在一个分支跑 npm run build（要 10 分钟），又想在 main 继续写代码：

git worktree add ../build-task feature/heavy-build
cd ../build-task && npm run build &   # 后台编译
cd ../my-project                       # 回主线继续干活，互不影响

场景 5：代码审查（Review）

同事让你 review 一个 PR，但你不想到线上去看，想本地跑起来：

git fetch origin pull/123/head:pr-123
git worktree add ../review-pr pr-123
cd ../review-pr
# 本地仔细看、跑测试，看完 remove 掉

五、工作原理（看一眼就懂）

执行 git worktree add ../hotfix main 后，仓库结构是这样变化的：

• 主仓库 my-project/.git 里会多出一个 worktrees/ 目录，记录所有附加工作区的元数据。
• 新目录 ../hotfix/.git 不是一个文件夹，而是一个文件，内容类似：
  gitdir: /path/to/my-project/.git/worktrees/hotfix
• 所有 commit、对象库（objects）、远程配置全部共享主仓库，新目录只存工作文件 + 一个 HEAD 指针。

所以 worktree 几乎不额外占空间，且任何 worktree 里的 commit/pull/push 都会立即对所有 worktree 可见（因为共享同一份对象库）。

六、常用进阶技巧

1. 一行命令建分支+目录

git worktree add -b feature/new-api ../new-api

2. 基于某个历史 commit 创建

git worktree add ../old-version abc1234

3. 停靠点（detached HEAD）用于实验

git worktree add --detach ../experiment
# 在这里随便改、随便试，不影响任何分支

4. 删除时报错"contains modified or untracked files"时强制删除

git worktree remove --force ../experiment

七、注意事项（避坑指南）

1. 同一个分支不能被两个 worktree 同时 checkout（Git 会报错防止冲突）。这是合理的保护机制。
2. 删除 worktree 目录要用 git worktree remove，不要直接 rm -rf，否则会留下"僵尸记录"，需要 git worktree prune 清理。
3. node_modules / target / dist 等不共享：每个 worktree 是独立的工作区，构建产物要各自生成（建议配合 monorepo 或 pnpm 缓存）。
4. IDE 配置：每个 worktree 可以用独立的 VSCode 窗口/配置，互不干扰，反而更清爽。

八、什么时候不该用 worktree？

• 只是线性开发一个功能、偶尔切个分支 → git checkout 够了，别过度设计。
• 需要在完全隔离的环境（不同 Git 配置/凭证）→ 用 git clone 更合适。
• 引入独立的外部项目 → 用 git submodule。

九、总结

git worktree 给了你"多个平行的现在"。当你厌倦了 stash、checkout、再 stash pop 的反复横跳，它就是答案。

记住核心一句话：同一仓库、多个目录、各 checkout 不同分支、共享一切 Git 数据。

---

如果这篇文章对你有帮助，欢迎点赞收藏 ❤️ 有问题欢迎评论区交流～