Codex 本地环境排查：依赖、命令和项目路径不对怎么办

适用场景

这篇手册适合遇到这些问题的用户：Codex 运行 npm run dev 失败、找不到命令、依赖缺失、环境变量缺失、开发服务器启动不起来，或者 Codex 明明改了代码但无法验证。

OpenAI 官方 Codex App 文档把 local environments 作为本地项目运行和验证的基础能力。排查时要先确认项目根目录和命令，再看依赖和环境变量。

步骤 1：确认当前目录是项目根目录

先运行：

pwd
ls

Windows PowerShell 可以运行：

Get-Location
Get-ChildItem

确认当前目录里是否有 package.json、pyproject.toml、Cargo.toml、go.mod 或项目自己的配置文件。

如果 Codex 在错误目录运行命令，再复杂的修复都可能跑偏。

步骤 2：找到项目实际命令

不要猜命令。先查看项目脚本：

cat package.json

或者让 Codex 读取 README：

请阅读 README 和 package.json，列出这个项目的启动、lint、test、build 命令。
不要修改文件。

确认命令后再运行。

步骤 3：检查依赖是否安装

前端项目常见问题是依赖没安装。先看项目使用哪个包管理器：

• 有 pnpm-lock.yaml：优先 pnpm install
• 有 package-lock.json：优先 npm install
• 有 yarn.lock：优先 yarn install

依赖安装会联网，也可能修改 lockfile。让 Codex 执行前，先确认命令和风险。

步骤 4：检查环境变量

如果启动时报 Missing API key、DATABASE_URL is required，说明环境变量缺失。

不要把真实密钥直接发给 Codex。可以让 Codex 做两件事：

请根据报错说明缺少哪些环境变量。
不要要求我提供真实密钥。
请给出 .env.example 中应该出现的变量名和说明。

真实密钥应该由你自己放进本地 .env，并确保不会提交到 Git。

步骤 5：启动开发服务器并记录输出

运行开发命令：

pnpm dev

如果失败，让 Codex 基于终端输出定位：

请根据当前终端输出判断启动失败原因。
只修改和启动失败直接相关的文件。

不要只说“跑不起来”。终端输出是定位问题的关键证据。

步骤 6：验证修复是否真的完成

修复后至少运行一个明确命令：

pnpm lint
pnpm build

具体命令按项目实际情况调整。最终让 Codex 说明：

• 改了哪些文件。
• 运行了哪些命令。
• 命令是否通过。
• 如果没跑，原因是什么。

常见错误

不要在错误目录安装依赖。

不要混用包管理器，比如项目用 pnpm 却运行 npm install。

不要把真实 .env 内容提交给 Codex 或 Git。

不要只修代码不运行验证。本地环境问题必须靠命令输出闭环。

小结

本地环境排查的顺序是：目录、脚本、依赖、环境变量、开发服务器、验证命令。每一步都基于当前项目证据，不靠猜。