worktree 是独立目录，产物与配置都隔离

更新于 2026-07-15

**git worktree 不是「在当前目录切了个分支」，而是「分支 + 一个独立文件夹」。因此在 worktree 里跑出来的服务、以及它的 `.env.local`，都只在那个目录生效：主目录照旧编译、照旧读自己的配置。看不到新效果、或改了环境变量不生效，先确认服务是从哪个目录启动的。**

一、两个典型症状

  1. 「为什么其他分支能直接编译出效果，你的却是独立的」 因为改动在隔离目录里，主目录跑的服务当然看不到。要看到效果只有两条路：进 worktree 目录启动服务，或把分支 merge / cherry-pick 回主目录（主目录若脏改动多，先评估冲突风险）。
  2. 「环境变量到底在哪个文件改」 看服务从哪个目录启动：在哪个目录跑 pnpm dev，就改哪个目录的 .env.local。worktree 有自己的 .env.local，改主目录那份不会生效。

二、可迁移的判断

  • 配置是就近解析的，不是全局的：报错「key 没配」时先确认进程的工作目录，再确认改的是不是那份文件。
  • 隔离目录的收益与代价是同一件事：好处是不污染主目录的一堆未提交改动；代价是产物与配置都不共享，必须显式合并或对齐。
  • 分支 ≠ 目录。说「切到某个分支看效果」之前，先确认那个分支 checkout 在哪个目录。
  • 分支是目录级状态，不是会话级：同目录开多个会话会互相抢分支（见 同目录多会话会抢分支）。

三、worktree 里连不上的两个变体

  1. 接口返回 500 空响应：.env.local 不被 Git 复制到新 worktree，认证配置校验失败 → POST /api/login 返回 500 空体。做法是软链接到主项目那份（ln -s），链接不复制密钥，主项目改配置后两边同时生效。
  2. 所有页面 404：next dev 与 next build 共用 apps/web/.next，生产构建覆盖了正在运行的开发路由产物 —— 进程还活着，路由清单已失效。跑 next build 前先停 dev。

另一个连带症状值得记住：前端假设「失败响应一定是 JSON」而直接 res.json()，空响应就抛 Unexpected end of JSON input，把真正的 500 错误遮住了。错误处理不健壮会把根因藏起来，排查时先看网络层的真实状态码，别被前端异常误导。

相关