Codex 读懂配置、环境变量和启动脚本

配置问题，通常不是“少写一行”

很多项目第一次启动失败，表面上是端口占用、数据库连不上，或者页面拿不到接口地址。真正的原因往往藏在几层配置之间：package.json 调了哪个脚本，脚本又传了什么参数，程序从哪些文件读取环境变量，最后哪个值覆盖了哪个值。

如果没有先把这条链路读清楚，直接改 .env 可能只让本地暂时跑起来，随后又把测试环境的行为改坏。真实密钥、内部地址和个人路径也可能因此进入截图、提交记录或聊天记录。

这篇文章用一个最小 Node 示例说明一套读法。示例中的服务地址、令牌和数据库名都是虚构值，不能连接任何真实服务。你可以把相同步骤套到前端项目、后端服务、脚本仓库或 monorepo 的某个应用上。

先画出“启动到配置”的路径

拿到陌生项目时，我先不打开 .env，而是按下面的顺序找入口：

package.json scripts
        ↓
启动脚本（node、tsx、vite、docker compose）
        ↓
入口文件（src/server.ts）
        ↓
配置加载（process.env、dotenv、配置模块）
        ↓
端口、数据库、第三方服务和功能开关

顺序很重要。先知道程序怎么启动，再看它在哪里加载配置，最后才判断某个变量应该写在哪里。否则只看到一个变量名，很难知道它是构建时使用、启动时使用，还是运行过程中才读取。

先分清三件事：配置文件、环境变量、启动参数

这三者经常同时出现在一条启动命令里，但职责不同：

比如下面这条命令同时用了三层信息：

$env:APP_MODE = "check"
npm run dev -- --port 4317

APP_MODE 属于当前 PowerShell 进程的环境变量，--port 4317 是传给脚本的启动参数，而脚本仍可能继续读取 .env 或配置模块。排查时要分别记录，不能把“命令行里出现过”理解成“配置文件里已经保存”。

PATH 决定“能不能找到命令”

安装成功不等于当前 shell 能找到程序。遇到 codex: command not found、rg is not installed 或 Windows 下的 不是内部或外部命令，先查解析结果，不要马上重装：

Get-Command codex -ErrorAction SilentlyContinue
Get-Command rg -ErrorAction SilentlyContinue
where.exe codex
where.exe rg

在 Linux、WSL 或 tmux 中对应的是：

command -v codex
command -v rg
printf '%s\\n' "$PATH"

如果安装器刚刚修改了 shell 配置文件，已经打开的终端未必会自动读取新 PATH。重新打开一个终端，或在确认文件来源后执行 source ~/.zshrc、source ~/.bashrc。不要把别人的 shell 文件整段复制过来；先用 type -a codex 或 Get-Command codex -All 确认当前命中的是哪一个版本。

GitHub 上的 Issue #34947 提供了一个可复核的 WSL 案例：Windows 11 + WSL2 + VS Code 终端中，关闭 appendWindowsPath 后，WSL 里的 powershell.exe、pwsh 和 powershell 都无法通过命令名解析；把 Windows PowerShell 目录临时加入 PATH 后，同一调用恢复。这个案例说明的是 PATH 和 WSL 互操作边界，不代表所有 WSL 安装都必须修改全局 PATH。

一则 Reddit 讨论也报告过 codex: command not found 和 rg is not installed，但 Reddit 当前无法通过公开读取接口核验正文与截图。它只能作为排查线索，不能替代本机的 where.exe、command -v 和版本输出。

这里有一个很容易被忽略的边界：Windows 应用、WSL 里的 Codex CLI 和集成终端可能不是同一个运行环境。一则 Reddit 案例里，界面显示 Agent 在 WSL 中运行、终端也使用 WSL，但“打开 config.toml”却打开了 Windows 用户目录下的 C:\Users\<name>\.codex\config.toml，而不是 WSL home 目录里的配置。这个截图只能作为排查案例，不能当作官方行为的完整说明；遇到类似问题，应以当前版本的界面、文档和实际路径为准。

图一　Windows/WSL 配置路径混淆案例。个人名已遮挡；路径和结论来自帖子原文，未独立验证。

第一步：从启动脚本开始

先读仓库状态、目录和包管理文件。这些都是只读动作：

git status --short --branch
Get-ChildItem -Force
Get-Content .\package.json

假设 package.json 的关键部分如下：

{
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "start": "node dist/server.js",
    "build": "tsc -p tsconfig.json",
    "test": "vitest run"
  }
}

这里至少有四个结论：

• npm run dev 运行的是 src/server.ts，并且会监听文件变化。
• npm run build 先把 TypeScript 编译到 dist，生产启动不直接读取 src。
• npm start 依赖已经存在的 dist/server.js，单独执行它可能会因为没有构建产物而失败。
• npm test 是验证配置解析是否改变行为的最小入口之一。

不要把 dev 和 start 当成同一件事。开发脚本可能注入本地参数、启用热更新，生产脚本则可能依赖构建阶段生成的文件和部署平台提供的环境变量。

如果脚本继续调用了别的脚本，继续展开。例如：

"dev": "cross-env NODE_ENV=development tsx watch src/server.ts"

这说明 NODE_ENV 由启动命令直接设置，不是从 .env 读出来。判断变量来源时，要把脚本中的前缀、PowerShell 的 $env:NAME=...、Docker Compose 的 environment 和 CI 配置一起算进去。

启动参数也要单独列出来。有些帖子会把 Electron、native module、CLI 和 --no-sandbox 串成一条很长的启动链，这类案例能说明“程序名后面的参数也会改变运行方式”，但不应直接变成入门教程的复制命令。对任意参数先回答三个问题：是谁解析它、它影响哪个进程、是否会降低安全边界。没有这三项证据，就把参数标成待确认。

除了脚本和命令行参数，配置文件本身也可能在应用设置里提供入口。Codex 的设置界面就在 config.toml 入口旁提示“编辑后重新启动 Codex”：有些配置只在进程启动时读取，改完文件不会自动改变已经存在的进程。排查“配置改了却没生效”时，先确认新值有没有被正在运行的进程真正读到，再决定要不要改下一处。

第二步：找到配置真正被读取的位置

接着搜索变量名和读取方式。优先搜 process.env、dotenv、loadEnv、config 等明确线索：

git grep -n "process\.env\|dotenv\|loadEnv\|config" -- ':!node_modules'

示例项目的 src/config.ts 可能是这样：

import "dotenv/config";

const required = (name: string) => {
  const value = process.env[name];
  if (!value) throw new Error(`Missing required environment variable: ${name}`);
  return value;
};

export const config = {
  nodeEnv: process.env.NODE_ENV ?? "development",
  port: Number(process.env.PORT ?? 3000),
  databaseUrl: required("DATABASE_URL"),
  apiBaseUrl: required("API_BASE_URL"),
  featureNewCheckout: process.env.FEATURE_NEW_CHECKOUT === "true"
};

读这段代码时，不要只抄变量名，要记录四件事：

1. 来源：是 process.env、配置文件，还是命令行参数。
2. 是否必填：required 这类校验会决定启动失败还是使用默认值。
3. 类型：环境变量本质上都是字符串，端口、布尔值和数组都需要显式转换。
4. 默认值：PORT 和 NODE_ENV 有默认值，不代表数据库地址也可以省略。

像 process.env.FEATURE_NEW_CHECKOUT === "true" 这样的写法也值得记下来。把变量写成 1、yes 或 TRUE，在这段代码里都不会得到 true。这类小差异经常让“配置明明写了却没生效”的排查绕远路。

第三步：整理配置来源和覆盖关系

不要笼统地写“环境变量优先级很高”。优先级由项目的加载代码、启动工具和部署平台共同决定。先在项目里找证据，再画表。

以 dotenv 的常见用法为例，可以先记录成这样：

同一个项目可能使用 dotenv-flow、Vite、Next.js、Docker Compose 或部署平台自己的加载规则，表格不能直接照搬。尤其是 .env.local，并不是 Node 或 dotenv/config 的通用默认文件名，只有项目代码或框架明确加载它时才会生效。检查方法是继续读入口和工具文档，并用一个无敏感信息的变量做实验：给 PORT 设置临时值，启动后观察监听端口，再恢复现场。

在 PowerShell 中，临时设置只对当前终端有效：

$env:PORT = "4317"
npm run dev
Remove-Item Env:PORT

不要把令牌写进命令历史。测试覆盖关系时，用端口或 APP_MODE=check 这类无害变量即可。

代理变量也是同一类问题。一个 GUI 应用、一个 CLI 进程和一个项目脚本，可能分别继承系统环境、启动它们的 shell 环境和项目自己的 .env。一则 Reddit 帖子提到 HTTP_PROXY、HTTPS_PROXY 在 CLI 和 GUI 中表现不同；这可以用来提醒排查方向，但不能据此断言 Codex 的所有版本都会自动读取 CODEX_HOME/.env。实际检查时，记录变量由谁设置、由哪个父进程继承，以及配置代码在哪里读取：

Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:NO_PROXY
Get-ChildItem Env:CODEX_HOME

如果需要做对比实验，用临时、无敏感信息的代理地址或 APP_MODE，不要把真实代理账号和密码写入截图、命令历史或项目文件。

.env.example 是说明书，不是密码保险箱

好的 .env.example 只告诉读者变量名、格式和必要说明：

NODE_ENV=development
PORT=3000
DATABASE_URL=postgres://user:password@localhost:5432/example_app
API_BASE_URL=https://api.example.test
FEATURE_NEW_CHECKOUT=false

这几个值都不能直接拿去连接生产服务。尤其要注意：

• 不要把真实 API key 替换成“看起来像真的”长字符串；用 replace-with-local-token 更安全。
• 不要把公司内网域名、真实数据库名或带个人身份的路径放进示例文件。
• .env.example 只描述变量，不代表项目已经有可用的本地依赖。
• 端口、数据库、对象存储和第三方 API 都要说明是本地模拟、测试环境还是必须人工申请。

先检查忽略规则：

git check-ignore -v .env .env.local
git ls-files .env .env.local .env.example

如果 .env 已经被 Git 跟踪，先暂停，不要直接删除或改写。那可能涉及历史泄密和团队协作，应由负责人决定如何轮换凭据、清理历史并通知部署环境。

第四步：把运行时前提列出来

配置文件只是其中一部分。启动脚本还可能隐含这些前提：

• Node、Python 或 Java 的版本由 .nvmrc、volta、pyproject.toml 或 CI 文件限定。
• 数据库、Redis、消息队列或本地对象存储必须先启动。
• 前端项目的 VITE_*、NEXT_PUBLIC_* 等变量可能在构建时打进浏览器，不能放私密令牌。
• Docker Compose、CI 和部署平台可能使用另一份变量名，不能只看本机 .env。

运行环境本身也是前提之一。在 Windows 版本的 Codex 中，Agent environment 与集成终端 shell 也可能分别选择 WSL。它们决定“代码由谁执行”和“终端从哪里启动”，不等同于某个配置文件的绝对路径。先把两个选择记录下来，再去验证配置文件实际由哪个进程读取。

图二　Codex 环境选择界面。它只证明界面中的选择，不足以单独证明配置文件路径或所有变量的加载顺序。

把前提写成可验证的清单，比写一句“需要配置好环境”有用得多：

[ ] Node 版本符合 .nvmrc
[ ] npm install 已完成，未额外升级 lockfile
[ ] 本地数据库已启动，使用 example_app 数据库
[ ] DATABASE_URL 指向本机，不是生产域名
[ ] API_BASE_URL 使用测试服务或本地 mock
[ ] 端口 3000 未被其他程序占用

其中“未额外升级 lockfile”很容易被忽略。为了启动一个项目临时执行 npm install，可能带来依赖版本变化；如果只是调查配置，先用仓库现有的 lockfile 和安装命令。

用最小启动验证，而不是直接碰生产配置

配置调查的目标是证明“我知道程序从哪里取值”，不一定要把所有外部服务都连通。可以分三层验证。

1. 静态验证

确认脚本、入口、配置模块和 .env.example 互相对得上：

git grep -n '"dev"\|"start"\|"build"' -- package.json
git grep -n 'DATABASE_URL\|API_BASE_URL\|FEATURE_NEW_CHECKOUT' -- ':!node_modules'

2. 无副作用启动

如果项目提供 --help、配置校验命令或 mock 模式，优先运行它们。没有的话，使用虚构数据库地址并只启动到配置校验阶段，避免触发写入操作。文章中的示例只验证端口和必填变量，不执行迁移、不发送外部请求。

3. 正常运行验证

确认本地依赖明确属于开发环境后，再运行：

Copy-Item .env.example .env.local
npm run dev

看到服务监听在预期端口后，用 Ctrl+C 停止，并再次检查：

git status --short

如果工作区多出 .env.local，这是预期的本地文件；如果出现 lockfile、构建产物或配置文件改动，先判断它们是否由启动命令自动生成，不要顺手提交。

配置错误有时会在初始化阶段直接阻断程序，而不是等到真正执行任务时才出现。一张终端案例截图显示，Codex 先报 Error loading configuration: No such file or directory，随后 npm 又因 uv_cwd 报错；这类截图适合用来说明“先定位配置和工作目录，再判断包是否损坏”，但不能仅凭截图断言应该卸载或重装哪个包。

图三　配置加载阶段的错误案例。错误文本和个人路径已遮挡；未对原项目做复现，不应据此直接执行卸载、重装或删除配置。

图四　把三类配置看成进入同一个进程的三条输入线：先分别确认来源，再判断哪个值最终生效。图中只表达关系，不代表某个框架固定的加载顺序。

图五　排查时依次检查入口、配置和验证；遇到断点先停在当前层收集证据，不要直接跳到重装依赖或修改共享环境。

哪些配置可以改，哪些要先问

可以直接调整的通常是本机、可恢复、不会影响其他人的值，例如本地端口、日志级别和 mock 开关。涉及共享环境的配置要先确认：

“我只是想让服务启动”不是修改共享配置的理由。启动失败信息不足时，保留错误、记录已检查的变量和缺少的权限，把需要人工决定的事项列出来。

给 Codex 的配置调查提示词

如果让 Codex 先做调查，可以直接给出边界和交付格式：

请只读调查这个仓库的配置和启动路径，不修改文件、不安装依赖、不提交。

请按顺序检查：
1. git 状态、包管理文件和所有启动脚本；
2. 入口文件、配置加载模块和环境变量读取位置；
3. .env.example、忽略规则、Docker/CI/部署配置；
4. 开发、测试、预览、生产之间的变量差异；
5. 数据库、队列、第三方服务、端口等运行前提。

输出一张表：变量名、来源、是否必填、默认值、作用环境、敏感等级、证据路径。
所有密钥只报告“存在”，不要读取或回显值。无法确认的优先级标为“待验证”，并给出一个无副作用的验证命令。

验收时看三点：它有没有给出文件和行号证据；有没有区分事实、推断和待确认项；有没有在输出里回显秘密值。如果只得到一串环境变量名称，没有启动路径和运行前提，这次调查还不完整。

最后留下一份小清单

完成配置调查后，至少应留下这些信息：

启动入口：npm run dev -> tsx watch src/server.ts
生产入口：npm run build -> npm start
配置加载：src/config.ts，使用 dotenv/config
必填变量：DATABASE_URL、API_BASE_URL
带默认值：NODE_ENV=development、PORT=3000
本地依赖：PostgreSQL；未执行迁移
已验证：静态路径、端口覆盖、工作区状态
未验证：第三方 API 权限、生产部署变量
安全边界：未读取真实 .env、未回显令牌、未改共享配置

这份记录让下一位读者知道程序从哪里启动、值从哪里来，哪些结论已经验证，哪些地方仍需要负责人确认。到这里，项目的运行前提才算读清楚。

整理完成后，至少应能说明启动入口、配置来源、覆盖顺序和验证方式。真实密钥、内部地址和个人路径不要写入文章或提交记录。