006 实战:搭建开发环境
综合实战:用 Codex 从零搭建 Next.js 项目,配置 codex.yaml,完成第一个编码任务。
学习目标
完成本课程后,你将能够:
一、任务说明
本次实战将模拟真实开发场景:用 Codex 搭建一个**任务管理看板(Task Board)**的 Next.js 项目。
你将完成
- 用 `/init` 初始化 Next.js 14 + TypeScript 项目
- 编写 codex.yaml 设定项目规范
- 初始化 Git 仓库
- 用 Codex 创建第一个功能页面
- 生成测试并通过
二、第一步:初始化项目
在 Codex 中输入
/init 创建一个 Next.js 14 项目,要求:
- 名称:task-board
- 使用 TypeScript 严格模式
- 使用 Tailwind CSS
- 使用 src/ 目录结构
- 使用 App Router
- 包管理器:pnpm
- ESLint + Prettier 已配置Codex 会执行以下操作:
- 运行 `npx create-next-app@latest task-board` 并传递参数
- 进入项目目录
- 确认所有依赖安装完成
验证项目结构
在 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-CNCodex 会生成对应内容。你只需确认或微调。
四、第三步:配置 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 的执行流程
- **规划阶段**:Codex 列出文件清单,你确认后开始
- **创建类型定义**:`src/types/task.ts`
- **创建组件**:`TaskCard.tsx`、`TaskList.tsx`、`NewTaskButton.tsx`
- **创建页面**:`src/app/tasks/page.tsx`
- **验证**:运行 `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 等工具组合使用,构建多模型联合开发工作流。