module1
40 分钟

实战:搭建开发环境

学习进度

当前模块0/6 课
总进度0/36 课
学习时长0 分钟

学习目标

  • 用 Codex 的 `/init` 指令从零初始化一个完整项目
  • 编写项目级 codex.yaml 配置文件
  • 配置 Git 工作流,用 Codex 生成 commit message
  • 独立完成一个端到端的编码任务

006 实战:搭建开发环境

综合实战:用 Codex 从零搭建 Next.js 项目,配置 codex.yaml,完成第一个编码任务。

学习目标

完成本课程后,你将能够:

一、任务说明

本次实战将模拟真实开发场景:用 Codex 搭建一个**任务管理看板(Task Board)**的 Next.js 项目。

你将完成

  1. 用 `/init` 初始化 Next.js 14 + TypeScript 项目
  1. 编写 codex.yaml 设定项目规范
  1. 初始化 Git 仓库
  1. 用 Codex 创建第一个功能页面
  1. 生成测试并通过

二、第一步:初始化项目

在 Codex 中输入

/init 创建一个 Next.js 14 项目,要求:
- 名称:task-board
- 使用 TypeScript 严格模式
- 使用 Tailwind CSS
- 使用 src/ 目录结构
- 使用 App Router
- 包管理器:pnpm
- ESLint + Prettier 已配置

Codex 会执行以下操作:

  1. 运行 `npx create-next-app@latest task-board` 并传递参数
  1. 进入项目目录
  1. 确认所有依赖安装完成

验证项目结构

在 Codex 中执行:

帮我列出 task-board 的项目结构

预期输出应包括:`src/app/`、`tsconfig.json`、`tailwind.config.ts`、`package.json` 等。

三、第二步:配置 codex.yaml

在项目根目录创建 codex.yaml。你可以在 Codex 中直接说:

在项目根目录创建 codex.yaml,配置如下:

项目信息:
- 名称:task-board
- 类型:web
- 框架:Next.js 14
- 技术栈:TypeScript + Tailwind CSS + Prisma + PostgreSQL

编码规范:
- 缩进 2 空格,单引号,保留分号
- 组件用 PascalCase,文件名用 kebab-case
- 函数用 camelCase,常量用 UPPER_SNAKE_CASE
- 禁止 any 类型
- 每个函数最多 80 行
- 必须包含错误处理

自定义指令:
- 你是全栈工程师,精通 Next.js 和 TypeScript
- 组件放在 src/components/,按功能分子目录
- API 路由放在 src/app/api/,遵循 RESTful 规范
- 所有状态管理使用 React Context + useReducer
- Prisma schema 变更后必须运行 prisma generate

默认模型:o4-mini
交互语言:zh-CN

Codex 会生成对应内容。你只需确认或微调。

四、第三步:配置 Git 工作流

初始化 Git

# 在项目目录中
git init
git add .
git commit -m "chore: initial commit - Next.js 14 project setup"

让 Codex 管理后续提交

之后的提交都可以让 Codex 来写 commit message:

git diff --staged | codex "根据这些变更生成一条符合 conventional commits 规范的 commit message"

设置 Git Hook(可选)

在 codex.yaml 中配置 pre-commit hook:

hooks:
  pre_commit:
    - command: "pnpm lint"
      description: "提交前检查代码规范"
    - command: "pnpm typecheck"
      description: "提交前检查 TypeScript 类型"

五、第四步:第一个编码任务

任务:创建任务列表页面

在 Codex 中发起任务:

你是一个全栈 Next.js 工程师。请在 task-board 项目中创建任务列表功能。

功能需求:
1. 页面路由:/tasks
2. 展示一个任务列表,每项包含:标题、状态(待办/进行中/已完成)、创建时间
3. 顶部有一个"新建任务"按钮
4. 点击任务可以切换完成状态
5. 使用 Tailwind CSS 做响应式布局

技术要求:
- 使用 Server Component 做页面外壳,Client Component 做交互
- 任务数据先使用 mock 数据(之后会接入数据库)
- 类型定义放在 src/types/task.ts
- 组件放在 src/components/task/
- 参考 codex.yaml 中的编码规范

输出:
1. 先列出需要创建的文件清单
2. 逐个创建文件
3. 完成后运行 pnpm dev 验证

Codex 的执行流程

  1. **规划阶段**:Codex 列出文件清单,你确认后开始
  1. **创建类型定义**:`src/types/task.ts`
  1. **创建组件**:`TaskCard.tsx`、`TaskList.tsx`、`NewTaskButton.tsx`
  1. **创建页面**:`src/app/tasks/page.tsx`
  1. **验证**:运行 `pnpm dev` 确认无编译错误

六、第五步:生成测试

让 Codex 写测试

/test 为刚才创建的任务列表组件生成测试:
- TaskCard 组件:测试渲染、状态切换点击
- TaskList 组件:测试空列表显示、多任务渲染
- 使用 Vitest + @testing-library/react
- 测试文件放在对应组件同目录,命名为 *.test.tsx

运行测试

pnpm test

确认所有测试通过。

七、第六步:提交代码

生成 Commit Message

git add .
git diff --staged | codex "生成一条 conventional commits 规范的 commit message"

预期输出类似:

feat(tasks): add task list page with status toggle

- Add Task type definition
- Create TaskCard, TaskList, NewTaskButton components
- Add /tasks route with responsive Tailwind layout
- Add unit tests for all components

提交

git commit -m "feat(tasks): add task list page with status toggle"

八、模块 1 完成检查清单

检查项状态
[ ] 理解 Codex CLI 的定位,能区分它与 IDE 工具
[ ] 完成 Codex 安装与 API 密钥配置
[ ] 掌握 8 个核心指令的基本用法
[ ] 能用 RGC 方法构造高质量提问
[ ] 会配置 codex.yaml 项目规范
[ ] 独立完成了一次从初始化到提交的完整开发流程

九、本课总结

**核心要点:**

  • `/init` 可以在一条指令中完成整个项目脚手架搭建
  • codex.yaml 应该在新项目创建后**第一时间**配置
  • 用管道将 Codex 集成到 Git 工作流:`git diff | codex` 生成 commit message
  • 编码任务让 Codex 先输出文件清单,确认后再开始编写代码,这样更可控
  • 测试生成后用 `/review` 最后检查一遍,确保代码质量

**下一步:** 进入模块 2《多工具协同》,学习如何将 Codex 与 Cursor、GitHub Copilot、ChatGPT、DeepSeek 等工具组合使用,构建多模型联合开发工作流。

上一课
下一模块