Codex CLI实战：5个真实开发场景下的高效用法与避坑指南

金山毒霸电脑医生

350人浏览 · 2026-07-17 10:31:39

金山毒霸电脑医生 · 2026-07-17 10:31:39 发布

写这篇文章的起因很简单——网上关于Codex的文章，十篇有九篇在讲怎么安装、怎么付费。真正讲"装上之后怎么用"的内容几乎空白。用了三个月Codex CLI之后，我把日常开发中最常用的五个场景和踩过的坑整理出来，给已经装好但不知道怎么用的朋友一个参考。

一、环境准备（只说重点）

如果你还没装，Windows用户最简单的方式：

# 方式一：Scoop安装（推荐）
scoop install codex

# 方式二：直接下载预配置包
# 从 codex.ijinshan.com 下载，省去配环境变量

装完之后第一步，设置模型。默认模型表现一般，手动指定GPT-5系列：

codex --model gpt-5.3

第二步，创建.codexignore文件，否则Codex会扫描node_modules里所有文件——你会等到怀疑人生：

# .codexignore（语法和.gitignore一样）
node_modules/
dist/
build/
.vscode/
*.log

第三步，建议在codex工作目录下建一个CODEX.md文件，用来描述项目规范。Codex每次启动会读取这个文件作为系统提示：

# CODEX.md
- 项目使用TypeScript + Express
- 数据库是PostgreSQL，ORM用Prisma
- 测试框架Jest
- 代码风格：函数式优先，避免class
- 所有API接口必须有输入验证

二、场景1：生成完整的REST API接口

需求：为User模块新增一个"根据ID查询用户订单"的接口，包含分页。

直接对Codex说：

codex "add a GET /users/:id/orders endpoint with pagination (page & limit query params). Include Prisma query in the service layer, input validation, and Jest tests. Return 404 if user not found."

Codex的具体执行过程：

创建orders.controller.ts——路由处理
更新orders.service.ts——添加getOrdersByUserId方法
添加zod输入验证——page和limit的合法性检查
生成orders.test.ts——包括正常用例、边界值、用户不存在的404
自动执行npm test——六个测试用例一次通过

生成的核心代码示例：

// orders.service.ts（Codex自动生成）
export async function getOrdersByUserId(
  userId: number,
  page: number = 1,
  limit: number = 20
) {
  const skip = (page - 1) * limit;
  const [orders, total] = await Promise.all([
    prisma.order.findMany({
      where: { userId },
      skip,
      take: limit,
      orderBy: { createdAt: 'desc' },
      include: { items: true }
    }),
    prisma.order.count({ where: { userId } })
  ]);
  return {
    data: orders,
    pagination: {
      page, limit, total,
      totalPages: Math.ceil(total / limit)
    }
  };
}

整个过程五分钟，手动写至少要半小时。

三、场景2：重构臃肿的Service文件

项目中有一个2100行的user.service.ts，包含了用户相关的所有逻辑——注册、登录、资料修改、权限管理、密码重置全塞在一个文件里。

一句命令：

codex "refactor src/services/user.service.ts. Split it into smaller modules: auth.service.ts, profile.service.ts, password.service.ts, permissions.service.ts. Extract shared utilities. Keep all existing tests passing. Update all imports across the codebase."

Codex的做法值得一说——它不是粗暴地切成几块就完事，而是：

先分析当前文件的所有导出函数和它们的依赖关系
按职责分组后逐一创建新文件
提取公共工具函数到user.utils.ts
更新整个项目中所有import路径
每切完一个模块就跑一次测试，保证不挂

重构过程中有两个测试挂了（循环依赖问题），Codex自动识别并修复。最终2100行的文件拆成了5个文件，平均每个200-400行。

四、场景3：自动修复Lint错误

CI/CD里挂了237个ESLint错误，手动修得一个个点。Codex一句话：

codex "fix all ESLint errors in the project. Run npx eslint --fix first, then manually fix remaining issues. Don't disable rules."

执行过程：

先跑npx eslint --fix（自动修复了约180个）
剩下的逐个分析：主要是no-unused-vars、@typescript-eslint/no-explicit-any、import/order
自动补充缺失的类型定义
调整import顺序

修完后自动跑一遍测试确认没有引入新问题。

五、场景4：生成数据库迁移

需求：为三个表添加软删除支持（deleted_at字段）。

codex "add soft delete support to users, orders, and products tables. Generate migration files, update Prisma schema, add middleware to filter out soft-deleted records by default, and add tests."

Codex完成后你得到的是：

一个migration SQL文件
更新后的schema.prisma
一个Prisma middleware自动过滤deleted_at IS NOT NULL的记录
测试覆盖软删除后的增删改查

核心的middleware代码：

// Codex自动添加的软删除中间件
prisma.$use(async (params, next) => {
  if (params.action === 'findUnique' || params.action === 'findFirst') {
    params.action = 'findFirst';
    params.args.where = {
      ...params.args.where,
      deletedAt: null
    };
  }
  if (params.action === 'findMany') {
    params.args.where = {
      ...params.args.where,
      deletedAt: null
    };
  }
  return next(params);
});

六、场景5：排查线上Bug

凌晨三点收到告警：/api/checkout接口500错误。从床上爬起来，把报错栈甩给Codex：

codex "there's a 500 error on the /api/checkout endpoint. Here's the error:
TypeError: Cannot read properties of undefined (reading 'price')
  at OrderService.calculateTotal (/app/src/services/order.service.ts:142)
  at CheckoutController.processCheckout (/app/src/controllers/checkout.controller.ts:56)"

36秒后，Codex给出诊断：

根因：order.service.ts第142行，products数组中某个元素没有price字段。
数据库中存在关联的product_id但该商品已被删除（products表中有该id的记录但status='deleted'），
导致Prisma include返回null而非跳过。

修复方案：在Prisma查询的include条件中添加status: 'active'过滤。

然后自动应用修复、跑测试、生成commit message。整个过程不到两分钟。