Codex CLI 多文件操作与大型代码库完整指南（2026）
Codex CLI 不只是处理单个文件——它可以在一次任务中读取、修改、创建多个文件，协调跨文件的重构。但大型代码库有其挑战：上下文窗口有限、文件间依赖复杂、重构范围难以控制。本指南介绍在大型项目中高效使用 Codex CLI 的完整策略。
1. Codex CLI 如何处理多个文件
Codex CLI 在 suggest 模式（默认）和 auto-edit 模式下均可主动读取项目中的相关文件。你不需要手动把文件内容粘贴到提示词中——Codex 会根据你的描述自动定位并读取涉及的文件。理解以下三个核心机制有助于更好地利用这一能力：
- 主动索引：Codex 在任务开始时会扫描工作目录（遵守 .codexignore 规则），建立文件索引。
- 按需读取：执行任务过程中，Codex 按需读取相关文件的完整内容，而不是一次性加载所有文件。
- 独立上下文：每个任务（每次
codex命令调用）有独立的上下文，不同任务之间不共享状态。如果需要跨任务传递信息，应使用 AGENTS.md 或在提示词中明确说明。
单次任务中操作多个文件的示例
# 方法一：直接列出文件
codex "重构以下模块，将重复的错误处理逻辑提取为共享函数：
- src/api/users.ts
- src/api/products.ts
- src/api/orders.ts
提取的函数放到 src/utils/errorHandler.ts"
# 方法二：按范围描述
codex "把 src/components/ 下所有 class 组件转换为函数组件，保持 props 接口不变"
# 方法三：按功能描述
codex "把用户认证相关代码（登录、注册、token 刷新）从 src/app.ts 中拆分出来，
创建独立的 src/modules/auth/ 目录，包含 router.ts、controller.ts、service.ts"Codex CLI 还支持通过 --context 参数手动指定上下文文件，以确保某些关键文件一定被读取：
# 强制包含特定文件作为上下文
codex "重构 src/api/users.ts，遵循 src/api/products.ts 中的代码风格" \
--context src/api/products.ts \
--context src/types/global.d.ts对于跨模块的大型重构，在提示词中给出清晰的"输入-输出"映射是最有效的方式：明确说明哪些文件是读取来源，哪些文件是要修改或新建的目标，可以大幅减少 Codex 的猜测和误操作。
2. 上下文窗口管理
上下文窗口是 AI 模型在单次处理中能"看到"的文本总量。对于 Codex CLI，上下文窗口直接决定了单次任务能处理的代码量上限。了解不同模型的上下文窗口大小，有助于制定合理的任务拆分策略。
| 模型 | 上下文窗口 | 约等于代码量 | 适合场景 |
|---|---|---|---|
| o4-mini（默认） | 128K tokens | ~9 万行代码 | 绝大多数项目 |
| GPT-4.1 | 1M tokens | ~70 万行代码 | 超大型代码库 |
| o4-mini-high | 128K tokens | ~9 万行代码 | 需要更深推理 |
优化上下文使用的策略
- 聚焦相关文件：提示词中明确指定涉及的文件，避免 Codex 扫描整个代码库
- 用 .codexignore 排除无关内容（见下节）
- 拆分大任务为小步骤：一次专注一个模块
- 提供架构摘要而非完整代码：在 AGENTS.md 中描述项目结构，让 Codex 了解全局而不需要读取每个文件
当任务超出上下文时
# 错误做法：一次性重构整个大型代码库
codex "重构整个 src/ 目录，统一错误处理方式" # 可能超出上下文
# 正确做法：分模块进行
codex "只重构 src/api/ 下的 3 个文件（users.ts、products.ts、orders.ts），统一错误处理"
codex "现在重构 src/services/ 下的同类问题"
codex "最后重构 src/utils/ 下的相关代码"另一个常见错误是在提示词中粘贴大量代码。应优先让 Codex 直接读取文件，而不是把代码复制到提示词中——后者会占用大量 token，实际上减少了可处理的代码量。
3. .codexignore — 精准控制访问范围
.codexignore 文件的语法与 .gitignore 完全相同，放在项目根目录下，用于告诉 Codex CLI 哪些文件和目录不需要扫描。合理配置 .codexignore 可以显著减少 Codex 处理的文件数量，提高响应速度和输出质量。
# 创建 .codexignore（语法与 .gitignore 相同）
cat > .codexignore << 'EOF'
# 依赖和构建产物（通常无需 AI 访问）
node_modules/
.next/
dist/
build/
coverage/
.cache/
# 大型数据文件
*.sql
*.csv
*.parquet
data/
# 二进制文件
*.jpg
*.jpeg
*.png
*.gif
*.ico
*.pdf
*.docx
*.xlsx
*.zip
*.tar.gz
# 敏感配置
.env
.env.local
.env.production
secrets/
*.key
*.pem
# 日志和临时文件
*.log
tmp/
temp/
EOF.codexignore 添加到 git 版本控制（不要加到 .gitignore），让团队成员共享相同的 Codex 访问范围配置。这样可以确保整个团队在使用 Codex CLI 时获得一致的行为。
查看 Codex 当前能访问哪些文件
# 类似 git ls-files，可以用 find 检查排除效果
find . -not -path './node_modules/*' -not -path './.next/*' -name '*.ts' | wc -l
# 更全面地检查所有 TypeScript 和 JavaScript 文件数量
find . \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' \) \
-not -path './node_modules/*' \
-not -path './dist/*' \
-not -path './build/*' | wc -l对于 Monorepo 项目，你可以在子目录中放置独立的 .codexignore 文件，实现更细粒度的控制。子目录的 .codexignore 会与根目录的规则叠加生效。
4. 大型项目的 AGENTS.md 配置
对于大型代码库，AGENTS.md 的作用尤为关键。它让 Codex 无需读取所有文件就能了解项目架构、关键约定和操作规则。一份好的 AGENTS.md 可以把每次任务所需的上下文量减少 60% 以上。
# Large Monorepo — AGENTS.md
## 项目架构
这是一个 Turborepo Monorepo，包含以下 package：
- apps/web：Next.js 15 前端（React 19 + Tailwind）
- apps/api：Fastify 后端（Node.js 20 + TypeScript）
- packages/ui：共享 UI 组件库
- packages/db：数据库 Schema（Drizzle ORM + PostgreSQL）
- packages/shared：共享工具函数和类型
## 关键约定
- 所有 package 使用 pnpm workspace
- 跨 package 引用用 @repo/ 前缀（如 @repo/ui、@repo/db）
- 每个 package 有自己的 tsconfig.json，继承根目录 tsconfig.base.json
- 数据库类型从 packages/db/schema.ts 生成，不要手动定义
## 修改规则
- 修改 packages/db/schema.ts 后，必须提示我运行 drizzle-kit generate
- 修改 packages/ui 组件时，保持向后兼容（其他 app 依赖这些组件）
- apps/api 的环境变量通过 apps/api/.env.example 查看，不要硬编码
## 测试要求
- apps/web：vitest + @testing-library/react
- apps/api：vitest + supertest
- packages/*：vitest
- 新功能必须附带测试文件为子目录设置独立 AGENTS.md
在 Monorepo 中，每个 app 或 package 可以有自己的 AGENTS.md，提供更具体的约束。Codex 会自动合并根目录和当前操作路径下的所有 AGENTS.md 文件。
# apps/api/AGENTS.md — 只影响 API 模块的操作
cat > apps/api/AGENTS.md << 'EOF'
# API Module — 额外约束
## 路由规范
- 所有路由版本化：/api/v1/
- 响应格式：{ data, meta, error }
- 分页参数：page, pageSize, total
## 数据库操作
- 不得直接 SQL，使用 Drizzle ORM
- 事务操作用 db.transaction()
- 查询超时设置 5s
EOF5. Monorepo 支持（Turborepo / Nx / pnpm workspaces）
Codex CLI 天然支持 Monorepo 结构，无需额外配置。以下是四个常见的 Monorepo 工作流实战示例：
示例一：跨 package 重构
codex "把 apps/web 和 apps/api 中重复的 User 类型定义合并到 packages/shared/types.ts，
更新两个 app 中的 import 路径（使用 @repo/shared）"示例二：批量更新依赖
codex exec "检查 packages/ 下所有 package.json，找出使用不同版本的共享依赖（如 zod、dayjs），
统一到最新稳定版，更新 pnpm-lock.yaml"示例三：创建新 package
codex "在 packages/ 下创建新的 @repo/logger package：
- 基于 pino
- 支持结构化日志
- 统一 log level 配置
- 在 apps/api 中替换现有的 console.log
按 packages/shared 的目录结构创建"示例四：同步 API 类型（后端 → 前端）
codex "从 apps/api/src/routes/ 中提取所有 API 的请求/响应类型，
生成 packages/shared/api-types.ts，
更新 apps/web 中的 API 调用处使用新类型"对于使用 Turborepo 的项目，Codex CLI 能够理解 turbo.json 中的任务依赖关系，并在建议修改时考虑构建顺序。在 AGENTS.md 中明确说明 Turbo pipeline 配置，可以进一步提升 Codex 对项目构建逻辑的理解。
nx.json 的关键配置和各个 library 的 tags，帮助 Codex 理解模块边界和依赖约束。
6. 增量重构策略
对于大型历史代码库，增量重构是唯一可行的可持续方案。以下是经过实践验证的四步工作流。
为什么不能一次性重构整个大型代码库
- 单次任务可能超出上下文窗口，导致遗漏或错误
- 修改范围太大，code review 几乎不可能做到位
- 测试失败时难以定位具体原因，调试成本极高
- 合并冲突风险高，尤其在多人协作环境中
- 心理压力大，容易中途放弃
推荐的增量重构流程
第一步 — 建立地图（在 AGENTS.md 中记录）：
codex "分析 src/ 目录结构，为 AGENTS.md 生成一份模块依赖图（ASCII 格式）
和每个模块的重构优先级（高/中/低），优先处理被多个模块依赖的核心模块"第二步 — 从叶节点开始（最少依赖的模块）：
codex "重构 src/utils/date.ts（没有其他模块依赖它）：
- 使用 date-fns 替换手写的日期处理
- 添加完整类型注解
- 生成 src/utils/date.test.ts"第三步 — 更新 AGENTS.md 记录进度：
codex "在 AGENTS.md 的'重构进度'章节，标记 src/utils/date.ts 为已完成，
记录使用的新 API（date-fns），供后续模块参考相同风格"第四步 — 向内推进（处理依赖已重构模块的上层模块）：
codex "重构 src/services/user.ts（依赖已重构的 date.ts）：
- 使用新的 date-fns API
- 统一错误处理（参考 AGENTS.md 中的错误处理规范）"进度跟踪模板（在 AGENTS.md 中维护）
## 重构进度（2026-05-29）
✅ src/utils/date.ts — date-fns 迁移完成
✅ src/utils/string.ts — 清理完成
🔄 src/services/user.ts — 进行中
⬜ src/services/order.ts — 待处理
⬜ src/api/routes/ — 待处理7. 实战：大型 TypeScript 代码库重构案例
以下是一个将 5 万行 TypeScript 代码库从 CommonJS 迁移到 ESM 的完整实战案例，覆盖评估、配置更新、分阶段迁移和最终验证。
# 第一阶段：评估影响范围
codex "分析 src/ 中所有 require() 和 module.exports 的使用情况，
生成迁移清单：哪些文件、多少行、依赖关系，以及迁移风险评估"
# 第二阶段：更新配置文件（不动源代码）
codex "更新 package.json（添加 type: 'module'）、tsconfig.json（module: 'ESNext'）
和 jest.config.js（ESM 支持），先不动源代码"
# 第三阶段：从工具函数开始迁移（叶节点）
codex "把 src/utils/ 下所有文件从 CommonJS 改为 ESM：
require → import, module.exports → export
不改业务逻辑，每个文件独立修改"
# 第三阶段验证
npx tsc --noEmit && npm test -- --testPathPattern=utils
# 第四阶段：按模块逐步迁移（重复第三阶段流程）
codex "迁移 src/services/ 下的所有文件（依赖已迁移的 utils/）"
npm test -- --testPathPattern=services
codex "迁移 src/api/ 下的所有文件"
npm test -- --testPathPattern=api
codex "迁移 src/app.ts 和入口文件"
# 第五阶段：验证整体
codex exec "运行 tsc --noEmit 和 npm test，收集所有错误，生成修复清单"这个案例的关键经验是：配置先行，代码后改。先更新所有构建配置，确保工具链支持 ESM，再逐步迁移源代码。每个阶段结束后运行测试，保证不引入新的错误。
./utils/date.js 而不是 ./utils/date）。让 Codex 在迁移每个文件时同步修复这些 import 路径，避免在最后阶段集中爆发大量错误。
8. 常见问题 FAQ
Codex CLI 可以同时修改多个文件吗？
可以。Codex CLI 在一次任务中可以读取、修改、创建多个文件。在提示词中列出相关文件路径，或描述范围（如"重构 src/ 下所有 TypeScript 文件"），Codex 会自动处理所有涉及的文件。在 suggest 模式下，Codex 会先展示所有将要修改的文件列表，让你确认后再统一应用，这是多文件操作最安全的方式。
Codex CLI 支持大型代码库（10 万行以上）吗？
支持，但需要策略。对于大型代码库，推荐：
- 用
.codexignore排除 node_modules 等无关目录，减少扫描范围 - 把大任务拆分为小步骤，每次聚焦一个模块（500 行以内）
- 在 AGENTS.md 中说明关键文件和架构，减少重复解释
- 针对具体模块而非整个项目下达指令
如果代码库超过 10 万行，考虑切换到支持 1M token 上下文的 GPT-4.1 模型（codex --model gpt-4.1）。
Codex CLI 的上下文窗口有多大？
默认模型 o4-mini 支持 128K token 的上下文窗口（约 9 万行代码）。GPT-4.1 支持高达 1M token（约 70 万行代码）。对于大多数中小型项目，128K 已经足够。但即使上下文窗口足够大，仍推荐通过 .codexignore 排除无关文件，分任务处理复杂重构，以获得更精准的输出质量。
如何对大型历史代码库进行增量重构？
推荐按模块逐步重构：先选定一个小模块（200-500 行），让 Codex 重构并确保测试通过；然后更新 AGENTS.md 记录已完成的模块和重构模式；再选择下一个依赖前者的模块，重复这一过程。始终从叶节点（没有其他模块依赖的工具函数）开始，向核心模块逐步推进。避免一次性重构整个代码库——这容易导致合并冲突和难以追踪的问题，大幅增加失败风险。