Codex CLI JavaScript/TypeScript 教程（2026）— AI 驱动的前端与 Node.js 开发

JavaScript/TypeScript 开发者面对庞大的生态系统——React、Next.js、Vue、Node.js、Bun……Codex CLI 理解这个生态，可以生成类型正确的 TSX 组件、完整的 API 路由、Jest 测试用例，并自动修复 tsc 编译错误。本指南覆盖 JS/TS 项目的完整配置和常用场景。

1. AGENTS.md — JavaScript/TypeScript 项目配置

在项目根目录放置 AGENTS.md 文件，让 Codex CLI 了解你的技术栈、代码规范和可执行的命令。以下是 Next.js 15 + TypeScript 项目的完整示例：

# Next.js 15 Project — AGENTS.md

## 技术栈
- Next.js 15 (App Router)
- TypeScript 5.5 (strict: true)
- React 19
- Tailwind CSS 3.4
- Drizzle ORM + PostgreSQL
- Vitest + Testing Library

## 代码规范
- 所有组件使用命名导出（不用 default export，除 page.tsx）
- Server Components 优先；需要交互的加 'use client'
- 路径别名：@ 指向 src/
- 组件文件名：PascalCase.tsx；工具函数：camelCase.ts
- 不得使用 any 类型；不得使用 @ts-ignore

## 允许的命令
- npm run dev/build/test/lint
- npx tsc --noEmit
- npx drizzle-kit generate/push/studio

## 禁止操作
- 不得修改 next.config.ts（除非明确要求）
- 不得修改 tailwind.config.ts
- Server Actions 必须有 'use server' 指令

2. TypeScript 类型错误自动修复

Codex CLI 最实用的能力之一是读取编译器错误输出并直接修复。以下是四种常见的 TypeScript 修复场景：

2.1 批量修复 tsc 错误

$ npx tsc --noEmit 2>&1 | codex "修复以上所有 TypeScript 编译错误：
- 不得使用 any 类型
- 不得使用 as 强制类型转换（as unknown as T 是绕过，也不允许）
- Optional chaining 优于 non-null assertion（!.）
- 逐个文件修复，不要改变业务逻辑"

2.2 为 JavaScript 文件添加 TypeScript 类型

$ codex "把 src/utils/api.js 转换为 TypeScript：
- 推断所有函数参数和返回值的类型
- API 响应使用泛型：ApiResponse<T>
- 错误类型使用 Error 的子类（不用 any）
- 保存为 src/utils/api.ts，更新所有 import"

2.3 复杂类型定义

$ codex "为 src/types/api.ts 添加以下类型：
- PaginatedResponse<T>：泛型分页响应（data、total、page、pageSize）
- ApiError：带 code、message、details 的错误类型
- SortableField<T>：从 T 的 key 中提取可排序字段名的工具类型
- DeepPartial<T>：递归可选类型"

2.4 修复 React 组件类型

$ codex "修复 src/components/DataTable.tsx 中的类型错误：
- generics 参数 T 没有约束，加 extends object
- column.render 函数类型不正确
- onSort prop 类型与使用方式不一致
保持组件 API 不变，只修复类型"

3. 自动生成 Jest/Vitest 测试

Codex CLI 可以分析已有组件或函数，生成覆盖率高、可直接运行的测试文件。以下覆盖五种常见测试场景：

3.1 组件测试（React Testing Library）

$ codex "为 src/components/LoginForm.tsx 生成 Vitest + Testing Library 测试：
- 渲染测试（无报错）
- 验证：邮件格式错误时显示错误信息
- 验证：密码少于 8 位时显示错误信息
- 验证：表单提交时调用 onSubmit prop
- 验证：loading 状态时禁用提交按钮
使用 vi.fn() 模拟 prop 函数"

3.2 API Route 测试（Next.js）

$ codex "为 app/api/users/route.ts 生成测试：
用 NextRequest 模拟请求，测试：
- GET /api/users（返回分页用户列表）
- POST /api/users（创建用户，含验证失败场景）
- 401 未授权（缺少 token）
- 422 参数验证失败
Mock Drizzle 数据库调用"

3.3 Hook 测试

$ codex "为 src/hooks/useDebounce.ts 生成测试：
- 立即返回初始值
- 在 delay 毫秒后更新（使用 vi.useFakeTimers）
- 快速连续调用只触发一次更新
- cleanup 时取消待执行的更新"

3.4 工具函数测试

$ codex "为 src/utils/formatters.ts 中的每个导出函数生成参数化测试（test.each），覆盖正常输入、边界值、null/undefined 输入"

3.5 E2E 测试（Playwright）

$ codex "用 Playwright 为购物车流程生成 E2E 测试：
1. 搜索商品
2. 添加到购物车
3. 修改数量
4. 填写收货信息
5. 确认订单
每步验证页面状态，失败时截图"

4. React 组件生成

Codex CLI 能够根据描述生成完整的 React 组件，包含类型定义、样式和测试文件。以下是五个典型场景：

4.1 完整表单组件

$ codex "创建 UserProfileForm 组件（src/components/UserProfileForm.tsx）：
- 字段：姓名、邮件、头像上传、个人简介（textarea）
- 用 react-hook-form + zod 做表单验证
- 用 Server Action 提交（不要 fetch/axios）
- 提交时显示 loading 状态
- 成功/失败后 toast 提示
- Tailwind CSS 样式，移动端适配"

4.2 数据表格组件

$ codex "创建通用 DataTable<T> 组件，支持：
- 列定义：columns: Column<T>[]（含自定义 render 函数）
- 分页（受控组件）
- 列排序
- 行选择（checkbox）
- 加载骨架屏
- 空状态
TypeScript 泛型完整，使用 Tailwind CSS"

4.3 无限滚动列表

$ codex "实现 InfiniteScrollList 组件：
- 用 Intersection Observer 检测滚动到底部
- 调用传入的 loadMore 函数加载更多
- 加载指示器
- 错误重试
- 用 React.memo 优化渲染
用 useReducer 管理状态，不用外部状态管理库"

4.4 复杂 Hook

$ codex "创建 useLocalStorage<T> hook：
- 从 localStorage 读取初始值，fallback 到 defaultValue
- 自动序列化/反序列化（JSON）
- 监听 storage 事件实现跨 tab 同步
- SSR 安全（window 不存在时 graceful fallback）
- TypeScript 泛型完整"

4.5 Server Component + Client Component 分离

$ codex "把 pages/blog/[slug].tsx 迁移到 Next.js App Router：
- 页面数据获取改为 async Server Component
- 用 generateStaticParams 实现 SSG
- 互动部分（评论、点赞）抽取为 Client Component
- 保持 SEO 和 Open Graph meta 标签
- 更新 import 路径使用 @ 别名"

5. Node.js / Express / Fastify 后端

Codex CLI 不仅擅长前端组件，同样可以生成高质量的 Node.js 后端代码，包括中间件、插件和实时通信功能：

5.1 Express 中间件生成

$ codex "为 Express 应用创建以下中间件（src/middleware/）：
- auth.ts：验证 JWT，将 user 附加到 req.user
- rateLimit.ts：基于 Redis 的滑动窗口限流（100 req/min/IP）
- errorHandler.ts：统一错误响应格式，区分 4xx 和 5xx
- requestLogger.ts：结构化日志（pino），记录方法、路径、耗时、状态码"

5.2 Fastify 插件

$ codex "创建 Fastify 插件 plugins/database.ts：
- 注册 @fastify/postgres（连接池）
- 提供健康检查路由 /health/db
- 优雅关闭时断开连接
- TypeScript 类型声明（fastify.pg 的类型扩展）"

5.3 WebSocket 处理

$ codex "用 ws 库为 Node.js 服务器实现实时聊天后端：
- 连接认证（JWT in query string）
- 用 Map 管理在线用户
- 支持频道（多房间）
- 广播和私信
- 断连清理和重连处理
- 完整 TypeScript 类型"

5.4 Bun 兼容

$ codex "把 src/server.ts 从 Node.js http 模块改为 Bun.serve API：
- 兼容现有路由逻辑
- 利用 Bun 的原生 .env 支持
- 添加 Bun.file 高性能静态文件服务
- WebSocket 用 Bun 原生 API"

6. Next.js 专项

Next.js 生态快速演进，Codex CLI 理解 App Router 的最新约定，帮你生成符合规范的数据获取、Server Actions 和性能优化代码：

6.1 App Router 数据获取

$ codex "在 app/products/page.tsx 实现数据获取：
- 用 fetch 直接请求 API（不用 useEffect）
- revalidate: 3600（每小时重新验证）
- generateMetadata 函数（动态 title 和 og:image）
- loading.tsx 骨架屏
- error.tsx 错误边界
- TypeScript 类型完整"

6.2 Server Actions

$ codex "为博客 CMS 创建 Server Actions（app/actions/posts.ts）：
- createPost(formData: FormData)：验证、保存到 DB、revalidatePath
- updatePost(id: string, data: Partial<Post>)
- deletePost(id: string)：软删除
- publishPost(id: string)：切换发布状态
每个 action 返回统一格式：{ success: boolean; error?: string }"

6.3 Route Handlers + Middleware

$ codex "创建 Next.js Route Handler app/api/upload/route.ts：
- POST 接受图片上传（multipart/form-data）
- 验证文件类型（只允许 jpg/png/webp）和大小（< 5MB）
- 上传到 Cloudflare R2
- 返回公开 URL
- 在 middleware.ts 中保护这个路由（需要登录）"

6.4 性能优化

$ codex "分析 app/dashboard/page.tsx 的性能问题并修复：
- 识别可以并行的数据获取（改为 Promise.all）
- 识别可以流式渲染的部分（用 Suspense 包裹）
- 检查不必要的 'use client' 组件（改回 Server Component）
- 优化图片组件（next/image 的 priority、sizes）"

7. JS/TS CI/CD（GitHub Actions）

将 Codex CLI 集成到 CI/CD 流程中，在每次 PR 时自动做 AI 代码审查，并配合 TypeScript 类型检查和测试：

# .github/workflows/js-ci.yml
name: JavaScript/TypeScript CI

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile

      - name: TypeScript Check
        run: pnpm tsc --noEmit

      - name: Lint
        run: pnpm eslint src/ --max-warnings 0

      - name: Unit Tests
        run: pnpm vitest run --coverage --reporter=verbose

      - name: Build
        run: pnpm build

      - name: Codex AI Review (on PR)
        if: github.event_name == 'pull_request'
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          npm install -g @openai/codex
          DIFF=$(git diff origin/main..HEAD -- '*.ts' '*.tsx')
          echo "$DIFF" | codex exec "Review TypeScript/React code changes for: type safety issues, React anti-patterns (missing deps in useEffect, key prop issues), accessibility problems, and performance concerns."

8. 常用 JS/TS 提示词速查表

以下是高频使用场景的提示词模板，可直接复制使用：

9. 常见问题 FAQ

Codex CLI 支持 TypeScript 吗？

完全支持。Codex CLI 可以读取和修改 .ts/.tsx 文件，理解 TypeScript 的类型系统，并生成类型正确的代码。在 AGENTS.md 中指定 tsconfig.json 的配置要求，Codex 会遵循严格模式（strict: true）的约束。

如何让 Codex CLI 生成 React 组件？

直接描述你需要的组件即可："创建 UserCard 组件，接受 user: User prop，显示头像、姓名、邮件，包含编辑和删除按钮，使用 Tailwind CSS 样式，导出为命名导出"。Codex 会生成完整的 TSX 文件包含类型定义。

Codex CLI 可以帮助修复 TypeScript 编译错误吗？

可以。运行以下命令即可自动修复类型错误：

$ npx tsc --noEmit 2>&1 | codex "修复以上所有 TypeScript 编译错误，不得使用 any 或 as 强制类型转换"

Codex CLI 支持 Next.js App Router 吗？

支持。Codex 理解 Next.js 的 App Router 约定（Server Components、Client Components、Route Handlers、Middleware 等）。在 AGENTS.md 中标注 Next.js 版本和是否使用 App Router，Codex 会生成符合规范的代码。