worktree 上代码跑不起来：`.worktreeinclude` 与初始化脚本怎么排

2026-08-09

用 Codex（OpenAI Codex）在 Git worktree 上干活，最常见的翻车不是模型写错代码，而是代码根本跑不起来：编译报找不到模块、测试起不来、脚本报缺配置。人很容易第一反应去怪模型，然后开始换模型、加提示词、反复重跑——方向从一开始就错了。

这个坑官方在《Troubleshooting》页里是列了条目的，原因写得很干脆：worktree 是另一个目录、继承的是 Git 里的文件，缺依赖。下面按排查文章的老规矩走一遍：现象 → 怎么确认 → 官方处置 → 处置后怎么验证 → 什么情况说明根本不是这个原因。

一、现象长什么样

典型表现有几类，共同点是”在主仓库目录里好好的，换个目录就不行”：

装过的依赖不见了：构建/测试命令报找不到包、找不到模块。
本地配置文件不见了：程序启动时报缺环境变量、缺某个本地配置。
生成物不见了：需要预先构建、预先下载才能跑的东西全没了。

注意这里有个认知陷阱。worktree 看起来就是”同一个仓库的另一份代码”，所以人会默认”和主目录一模一样”。实际上它一模一样的只有 Git 跟踪的那部分。你 .gitignore 掉的依赖目录、本地环境文件、缓存、构建产物，一个都不会跟过去——它们本来就不在 Git 里。

先说清一件事，免得读者对号入座错了：官方《Troubleshooting》页里的排查条目大多数是面向桌面应用的，worktree 这几条也在其中，本文引用它们时一律按官方文档口径写，我们没有在本机跑过任何 worktree 上的实际任务（本批全部实测只覆盖只读命令，一次模型对话请求都没发过）。

二、怎么确认就是这个问题

判定的核心思路只有一句：把 Codex 摘出去，人自己在那个目录里跑一遍。如果人跑也跑不起来，那就跟模型无关。

第一步，先确认 worktree 到底在哪个目录：

git worktree list

这条是 Git 自己的命令，Windows 上在 Git Bash、PowerShell、CMD 里都能跑，输出会把每个 worktree 的路径列出来。先把路径抄下来，后面几步都要用。

第二步，进到那个目录，手动跑一遍你项目自己的初始化和构建命令——就是新人 clone 完仓库要跑的那几条（安装依赖、生成配置、预构建）。这一步不需要 Codex 参与。跑通了，说明前面的失败确实是环境缺失；跑不通且报的错和 Codex 报的一样，那就更实锤了。

第三步，确认”少的到底是哪些文件”。用 Git 自己把被忽略的东西列出来：

git -C "<worktree 目录>" status --ignored --short

拿它和主仓库目录里同一条命令的输出对比，差集基本就是没跟过去的那批。想确认某个具体文件是不是被忽略规则拦下的，用：

git -C "<worktree 目录>" check-ignore -v .env

它会打印是哪条忽略规则命中的。Windows 上路径带空格务必加引号，反斜杠路径在 Git Bash 里容易被当转义符吃掉，写正斜杠更省事。

第四步，顺手排掉”其实是 Codex 自己没跑起来”的可能。在 codex-cli 0.147.0（Windows 11）上，codex doctor --summary 会分组打印检查项，Environment 组里有 git（打印 git version）、Configuration 组里有 config（正常时是 loaded）。我们在同一版本上故意传了一段语法不合法的 TOML（codex -c 'features=[unclosed' doctor --summary），doctor 没有崩溃退出，但 Notes 区出现了这一行：

✗ config       config could not be loaded - Fix the reported config error, then rerun codex doctor.

也就是说，配置坏掉的时候 doctor 照样能跑，而且会明确告诉你配置没加载成功。如果你看到的是这一行，那问题在配置，不在 worktree，别再往依赖上找了。

三、官方给的处置

《Troubleshooting》页对”代码在 worktree 上跑不起来”给的解法是两条，二选一或者组合：

通过本地环境跑初始化脚本——也就是让 worktree 建好之后自动执行那套”装依赖、生成配置”的动作，而不是指望文件自己出现。
用 .worktreeinclude 把被忽略的文件纳进来——针对那些本来就被 .gitignore 拦住、但新目录里确实需要的本地文件。

这里必须说清楚边界：官方排查页给到的就是这两个处置方向和 .worktreeinclude 这个文件名，再往下的细节它一个字没写。官方文档站另有一页名为《Worktrees》，但我们没有取到该页正文，所以 .worktreeinclude 的具体写法，本文一个字都不编，请直接查该页。这不是卖关子：排查文章里最坑人的就是”看起来很确定、实际是猜的”那部分，宁可让你多点一次官方链接，也不给你一个可能是错的写法。

顺带提一个很实用的小技巧：learn.chatgpt.com 上任何文档页的 URL 后面加 .md 后缀就能拿到 Markdown 版本，站点还提供 llms.txt（完整页面索引）和 llms-full.txt（合并全文），要塞给 AI 工具读比复制网页干净得多。

同样，网上那些”改个注册表""调个组策略""加个软链接”的偏方，本文一条都不给——官方没写的我们不编。

两条处置的取舍其实很好判断：

缺的是能重新生成的东西（依赖包、构建产物、缓存），走初始化脚本。这类东西复制过去反而容易带上旧版本、旧平台的二进制，重装比搬运干净。
缺的是生不出来的东西（本地密钥文件、只在你机器上有的配置、同事给你的那份环境文件），才是 .worktreeinclude 的场景。

顺带一提，这类本地文件里往往有 API key。示例里一律写成 <YOUR_API_KEY>，别在提交、截图、issue 里带真值。

四、处置完怎么验证

别只看”Codex 这回没报错”就算完，那是运气。按顺序验三件事：

回到判定命令。重跑一次 git -C "<worktree 目录>" status --ignored --short，确认之前缺的那批文件现在确实存在。
人再手动跑一次构建和测试。跑通了才算环境修好。这一步是硬门槛，跳过去等于没验。
再起一次 Codex 会话，把工作根显式指到 worktree。在 codex-cli 0.147.0（Windows 11）上，codex --help 里 -C, --cd <DIR> 的说明是”指定 agent 的工作根目录”。显式带上它，比”我以为当前目录是对的”可靠得多：

codex -C "<worktree 目录>" --sandbox workspace-write

如果这次会话还需要动 worktree 之外的目录，--add-dir <DIR> 的官方说明是”主工作区之外额外可写目录”，按需追加。

五、什么情况说明不是这个原因

排查最怕认准一个原因往死里试。下面几种情况，请立刻掉头：

A. 主仓库目录里也跑不起来。 那就是项目本身的问题——依赖版本、工具链、某人刚合进来的破坏性改动，跟 worktree 和 Codex 都没关系。

B. doctor 报的是 ✗ config。 前面第四步那一行，配置没加载成功。先把配置错误修掉再说，这时候补依赖是白补。

C. 团队约定的本地配置识别不到。 官方《Troubleshooting》页对这条给的原因是配置不在 .codex 文件夹里，解法是确保 .codex 文件夹在项目根；monorepo 要打开正确的目录。这和依赖缺失是两码事，症状却容易混。

D. 报的是写入失败，不是找不到文件。 那更像沙箱/权限侧。在 codex-cli 0.147.0（Windows 11）上，-s, --sandbox 的取值只有 read-only / workspace-write / danger-full-access 三个，传错会在参数解析阶段直接被拦下，报错原文是：

error: invalid value 'bogus-mode' for '--sandbox <SANDBOX_MODE>'
  [possible values: read-only, workspace-write, danger-full-access]

如果确认是可写范围不够，官方配置里对应的键是 sandbox_workspace_write.writable_roots（workspace-write 下额外的可写根）：

[sandbox_workspace_write]
writable_roots = ["<你的 worktree 目录>"]

以上为按官方文档键位组合的示例，未逐项实测，以官方文档为准。

E. 一堆莫名其妙的 worktree 冒出来。 官方对”计划任务产生了大量 worktree”给的处置是：归档不需要的计划运行；除非要保留 worktree，否则不要 pin。这是清理问题，不是跑不起来的问题。

F. 压根起错了执行目标。 官方列了”会话起错了执行目标（Local / Worktree / Cloud）“这一条，给的做法是取消运行后在 composer 里按上方向键找回原提示词，重来一次即可——提示词不用重打。这条属于桌面应用侧，本机未实测。

最后一句经验之谈：worktree 的价值是隔离，代价就是环境不会自己跟过来。把”新建 worktree → 跑初始化脚本”固化成一步，比每次事后排查省事得多。