Codex Handoff 后 .env 或依赖不见了怎么办？Local、Worktree 与忽略文件排查

先判断：丢的是代码，还是只丢了本地环境

本文适合 Handoff 后出现模块找不到、环境变量为空、数据库连不上、证书或本地配置缺失，但 Git 中的代码改动仍存在的开发者。如果是云端任务停在 Setup Script，先看Codex 云端环境初始化排查；如果只是想并行开发，先读Codex 与 Git Worktree 实践。

原创封面用两个独立代码空间和一座交接桥表示 Local 与 Worktree 的关系，不是 Codex 官方界面，也没有真实仓库或源码。

理解三个边界：仓库历史共享，工作目录独立，本地文件未必受 Git 管理

Git 官方把 worktree 定义为附着在同一仓库上的另一个工作目录。多个工作树共享大部分仓库元数据，却各自拥有实际检出的文件、HEAD 和索引状态。Codex 手册说明，托管 Worktree 默认从 Git 检出开始，因此仓库追踪文件会出现，但 Git 忽略或未跟踪的本地文件不会天然跟过去。

Handoff 会处理 Local 与 Worktree 之间的 Git 操作，并保持同一聊天关联原工作树；它不是整目录复制器。.env、.env.local、本地证书、编辑器配置、虚拟环境和依赖目录如果没有被跟踪，就不能仅凭交接动作保证出现。

第一步：确认 Codex 和终端到底在哪个目录

不要在主项目里看状态，却拿 Worktree 的报错来判断。先在发生问题的终端执行目录与 Git 识别命令，再把路径同 git worktree list 对照。Codex 托管工作树通常位于 $CODEX_HOME/worktrees，但应以当前设备的实际输出为准。

Windows PowerShell 可用 Get-Location，macOS/Linux 可用 pwd；后续 Git 命令跨平台一致。记录当前分支或 detached HEAD、仓库根目录和工作树列表，才能解释代码为什么出现在另一处。

• 运行 git rev-parse --show-toplevel，确认当前仓库根目录
• 运行 git worktree list --porcelain，查看每个工作树的路径、提交与分支
• 运行 git status --short --branch，确认当前改动与分支状态
• 运行启动或测试命令前，再打印一次当前目录，防止终端复用了旧路径

第二步：把缺失文件分成 tracked、ignored 与 generated

对每个缺失文件先问 Git，而不是直接复制。git ls-files --error-unmatch <path> 能确认它是否受跟踪；git check-ignore -v <path> 能显示是哪条忽略规则命中。Git 官方说明，.gitignore 只描述有意不跟踪的文件，已经被跟踪的文件不会因为后来加入忽略规则就消失。

若是源码或锁文件应该被跟踪却缺失，优先核对分支和提交；若是 .env 等敏感配置，保持忽略通常是正确做法；若是依赖或构建产物，应重建而不是提交。

第三步：谨慎使用 .worktreeinclude

Codex 手册提供 .worktreeinclude，让托管 Worktree 创建时复制匹配的 Git 忽略文件。它放在仓库根目录，语法类似 .gitignore。适合必须存在又不应提交的本地配置，例如 .env.local 或 config/secrets.json。

但不要把所有秘密、证书和整个依赖目录一股脑列进去。复制会扩大敏感信息暴露面，而且虚拟环境和依赖目录可能包含绝对路径、平台二进制或软链接，换目录后并不可靠。优先复制最小配置模板，在目标工作树中重新安装可再生依赖。

• 示例条目可包含 .env.local、config/development.local.json，只列任务确实需要的文件
• 不要列出已经受 Git 跟踪的文件；Codex 只复制匹配的 ignored files
• 源符号链接会被跳过，目标已存在文件不会被覆盖
• AGENTS.override.md 在 Codex 托管工作树中有专门复制规则，不必重复列入
• 修改 .worktreeinclude 后应新建测试 Worktree 验证，不要假设旧工作树自动补齐

第四步：让初始化脚本重建依赖，而不是复制依赖目录

依赖缺失时，推荐在 Codex Local Environment 的 setup 过程中执行项目已有的安装命令，并让锁文件控制版本。Node.js 项目通常依据项目约定使用 npm ci、pnpm install --frozen-lockfile 或等价命令；Python 项目应创建当前目录自己的虚拟环境，再按锁定依赖安装。不要把示例命令机械套到仓库，先看 README、AGENTS.md 和 CI。

Monorepo 还要确认命令是在仓库根目录还是子包目录运行。准备一条快速验证命令，例如版本检查、静态检查或小范围测试；初始化结束后先跑它，再让 Codex 继续修改，避免把环境故障误当成代码缺陷。

• 安装命令非交互、可重复，并且失败时返回非零状态
• 运行时版本、包管理器与锁文件匹配
• 不在日志中打印 Secret、完整环境变量或内部地址
• 并行工作树使用不同端口、临时数据库或缓存目录，避免互相占用
• 依赖安装完成后运行最小测试，再执行完整验证

第五步：Handoff 前后各留一份可比较的证据

交接前记录仓库根目录、工作树列表、Git 状态和关键命令结果；交接后在新目录重复同一组检查。若源码 diff 一致而环境文件不同，问题属于本地环境恢复；若 tracked diff 不一致，则回到分支、提交与 Handoff 状态继续排查。

验收时可参考Codex 测试证据与交付指南和任务说明模板，把期望目录、启动命令、需要复制的忽略文件和禁止触碰的 Secret 写清楚。

风险提示与结论

不要为了让 Worktree 跑起来，把 .env、私钥、Token、生产数据库口令提交到 Git，也不要把主项目的整个依赖目录直接拖过去。正确顺序是：确认目录 → 判断文件类型 → 最小复制忽略配置 → 在目标目录重建依赖 → 用同一测试验证。

ChatGPT Plus、ChatGPT Pro 或其他会员充值解决的是账号计划与产品访问，不能替代本地仓库配置、Git 基线和开发环境。Codex 功能与入口以当前官方文档和账号界面为准。[GPTUPCN 首页](/)是第三方中文信息与服务入口，并非 OpenAI 官方。