Codex新Worktree缺依赖怎么办？本地Setup脚本与Actions配置教程

同一项目在原目录能运行，新建Worktree却提示找不到依赖，不一定是代码坏了。Worktree位于不同目录，未纳入仓库的依赖和本地文件不会自然出现。Codex桌面本地环境支持Setup scripts和Actions：前者准备新工作区，后者便于重复执行常用操作。本文专门处理这一复现问题，不重复介绍分支隔离。

第一步：进入Codex本地环境设置

在ChatGPT桌面应用先选择Codex，再从设置面板配置Local environments。官方说明这项能力只在桌面Codex可用，不是普通网页聊天或CLI里任意同名配置。生成配置存放在项目根目录.codex，可按团队规则纳入Git共享。多项目仓库应打开包含共享.codex的正确目录。

先看项目已有README、锁文件与package.json，确认原目录究竟依赖什么。不要直接复制整个node_modules或本机用户目录到新Worktree，这既难复现，也可能把无关缓存和凭据带过去。先把“缺少依赖”与“缺少业务配置”分开记录。

第二步：确定适合项目的Setup命令

请只读检查这个练习项目的README、锁文件和已有脚本。列出新Worktree需要的运行时、依赖安装与构建步骤，区分可自动准备的文件和需要我提供的本地配置。不要安装、不修改文件、不复制密钥，先解释推荐命令为何适合该仓库。

官方用npm install和npm run build说明TypeScript项目的准备方式，但你的仓库可能采用其他包管理器。按锁文件与项目约定选择，已有package-lock.json并要求严格安装时可考虑npm ci；不要混用多种工具生成相互矛盾的锁文件。

Setup脚本在新聊天创建Worktree时自动运行，所以内容应适合重复执行，避免交互式输入、持续运行的开发服务器或删除用户文件。需要本地配置时使用项目允许的安全准备流程，不把真实.env内容写进将提交的脚本。

第三步：在设置中保存并检查生成文件

将已确认的准备命令填入Setup脚本。若macOS、Windows和Linux确有不同要求，使用平台专属脚本覆盖默认，不把只适用于某个终端的命令强塞给全体成员。保存后检查.codex内生成配置的差异，确认没有意外路径、用户名或秘密值。

示例准备流程（仅适用于已有相应锁文件与脚本的练习项目）：
npm ci
npm run build

验收重点：两步各自成功；构建失败时保留错误，不继续宣称准备完成。

这是项目命令示例，不是要求把一段文字原样当配置文件。具体配置通过当前桌面设置生成，避免从不明旧教程照抄可能已变化的字段名。将准备与运行分开，脚本结束后新聊天才更容易判断工作区是否就绪。

第四步：把常用运行和测试设为Actions

在同一本地环境中添加Actions，例如Run用于项目已有启动脚本，Test用于已有测试命令。官方说明它们显示在桌面顶栏，并在集成终端运行。Actions是快捷执行入口，不表示定时任务或后台一直运行；一次性排查仍可直接在终端执行。

示例Actions：
Run：npm start
Test：npm test

使用前确认package.json确实提供这些脚本；没有就按项目现有命令填写，不为了教程强行新增空测试。

第五步：新建Worktree验证整套流程

新建练习Worktree，观察Setup是否实际运行，再点Run或Test检查当前目录、退出状态与输出。原目录成功不算新工作区验收通过；顶栏按钮出现也不证明命令存在。若失败，先定位缺少依赖、版本或配置，不立即改业务代码。

检查生成文件与Git差异，确认不把依赖目录和私密配置意外提交。团队共享配置前说明适用平台和必要手动步骤。完成标准是新Worktree能独立完成准备，常用Actions能在正确目录运行，且失败会清楚呈现，而不是只在你当前电脑的旧目录可用。

官方资料

资料核对日期：2026年11月7日。

• OpenAI：Local environments