VSCode 配合 Git Worktree 实现多版本代码并行运行环境

在开发过程中，经常需要在不同分支上并行工作：比如修复生产环境的紧急Bug，同时开发新功能，还要切换回来调试老版本问题。过去，你大概率会用git stash或频繁git checkout，但总有那么几次，不是忘了提交就是搞乱了工作目录。

Git Worktree 就是为了解决这个问题而生的。它允许你在同一个仓库下创建多个工作目录，每个目录对应一个分支，互不干扰。但很多人第一次上手时，总会遇到几个“坑”，我们来逐一拆解。

VSCode 必须打开工作树目录本身，否则 Git 状态不生效

很多人会遇到一个尴尬局面：用 git worktree add 创建了新的工作目录，然后直接在 VSCode 中“打开文件夹”选择了它，却发现源代码管理视图一片灰色，状态栏显示“No source control providers”，甚至集成终端里 git status 都报错 fatal: not a git repository。

其实原因很简单：VSCode 并不会自动扫描主仓库下的所有子目录。它只在你明确用“File → Open Folder…”打开某个工作树路径时，才加载该目录下的 Git 上下文。所以，关键点在于：

• 确认该目录下存在一个 .git 文件（注意是文件，不是文件夹），内容类似 gitdir: /path/to/repo/.git/worktrees/feature-x
• 不要打开父目录或主仓库根目录——哪怕它看起来“更上层”，VSCode 就认这个物理路径
• 如果用了 GitLens 等插件，检查其设置里是否启用了 multi-worktree support（默认可能关闭）

创建工作树时 -b 参数决定分支是否存在，别漏掉

决定加不加 -b，本质上是在问“你是想检出已有的分支，还是新建一个本地分支”？弄错的话，可能导致后续 push 失败、远程追踪丢失，甚至误以为分支已经建好了。

• 想基于远程分支（如 origin/feature/login）拉取并检出同名本地分支 → 不加 -b：git worktree add ../feature-login feature/login
• 想新建一个本地分支（比如 feature/new-ui）并立即在新目录中检出 → 必须加 -b：git worktree add -b feature/new-ui ../feature-new-ui main
• 想临时调试某次提交 → 加 --detach：git worktree add --detach ../debug-e7f3d2a e7f3d2a

漏掉 -b 后，你在 git branch 里找不到该分支，git push 也会提示 “no upstream configured”。这时候需要补一句 git push -u origin feature/new-ui 来建立追踪。

多个 VSCode 窗口并行运行不同工作树，完全隔离无冲突

每个 worktree 都有自己独立的 index、HEAD、工作目录以及 node_modules（或 venv）。VSCode 启动时只读取当前打开路径的 .git 引用，不会跨目录干扰。

• 你在 feature/auth 窗口改了 package.json 并执行 npm install，完全不影响 hotfix/login 窗口的依赖状态
• 可以同时运行 npm run dev 和 npm test，它们各自基于不同分支的代码快照
• 状态栏右下角会清晰显示当前窗口的分支名及其工作树路径，比如 feature/auth | /path/to/repo-feature-auth

删除工作树前必须确保干净，否则 git worktree remove 拒绝执行

git worktree remove 默认会拒绝删除包含未提交更改或未推送提交的工作树，这其实是一个保护机制，不是 bug。

• 先检查该 worktree 目录下是否有未提交修改：git status --porcelain，输出为空才安全
• 若有修改但不想丢，可先 git add . && git commit -m "temp"，再删除
• 真要强制删除（比如调试完的临时 worktree），用 git worktree remove --force ../feature-debug。但务必确认没有遗漏重要改动
• 注意：--force 只删除 Git 关联记录，目录本身仍然留在磁盘上，需要手动 rm -rf

最容易被忽略的一点是：VSCode 窗口开着时直接删除 worktree，Git 会报错并且可能留下残留的锁文件。所以，务必先关闭对应的 VSCode 窗口，再执行删除命令。