实战案例：用 Codex 从零做一个 Next.js 教程网站

这个实战案例的目标很明确：做一个面向中文用户的 Codex 教程网站，名字叫 Learn Codex，技术栈使用 Next.js，最终部署在 Vercel，并且内容重点不是产品介绍，而是教程、命令说明、工作流和实战案例。

换句话说，这不是在做一个营销页面，而是在做一个内容型网站。这个定位会直接影响页面结构、SEO 方式、文章组织方式和后续更新节奏。

这个项目一开始并没有直接进入代码阶段，而是先确定了网站名字、部署平台、技术栈和站点定位。这里最重要的一点，是把范围收窄到 Next.js 加 Vercel 的教程站，而不是继续发散到后台、CMS、社区或复杂交互。

如果你一开始就让 Codex 做一个完整平台，结果通常会变得过重。更稳的做法是先把 MVP 范围框定清楚：首页、教程列表、文章页、关于页、基础 SEO 和首批内容。

项目骨架使用 create-next-app 初始化，采用 App Router、TypeScript 和 Tailwind CSS。这样做的好处是：结构稳定、Vercel 兼容度高、后面做静态内容也很方便。

在这一步里，Codex 的价值主要不是替你点命令，而是快速把基础项目从默认模板推进到可做内容站的形态，例如调整 layout、全局样式、页面层级和基础站点配置。

为了让教程站后续容易扩展，站点没有把文章写死在各个页面组件里，而是先抽出一个统一的内容数据结构。每篇文章都包含 slug、标题、描述、分类、阅读时长、发布日期和分节内容。

这一步很关键。因为一旦内容结构清晰，首页、列表页、详情页、相关推荐、上一篇下一篇这些能力都能围绕同一份数据生成，而不是每加一篇文章就去改很多组件。

首页、教程列表页、文章详情页和关于页是按核心路径优先级来做的。不是先抠细节视觉，而是先让网站具备真实可浏览结构。

这样做的原因很现实：教程网站最重要的是信息架构和阅读路径，视觉细节可以后补，但页面路径如果一开始就没理顺，后面每加内容都会返工。

首页最终没有做成那种重营销、轻内容的 Landing Page，而是做成了一个偏内容导航的首页：有主标题、有核心入口、有内容概览、有专题区块，也有必读内容和学习路径。

这个选择非常适合教程站。因为访客真正关心的是从哪里开始学、哪些内容最值得先看，而不是一堆品牌口号。

这个网站的内容不是单篇零散堆出来的，而是按入门、基础、工作流、实战、FAQ 这几个专题来组织。这样做后，用户进站以后不会只看到文章列表，而能感受到清晰的学习路径。

首批内容包括 Codex 是什么、第一次使用怎么跑通、怎样给 Codex 下任务、交互命令怎么用、完整 slash commands 清单等。这些内容都围绕真实使用问题，而不是抽象介绍。

这个项目里有一个非常典型的 Codex 协作场景：中途发现文章方向理解错了。原先写的是泛化的内置命令说明，但用户真正要的是像 /model、/permissions、/status 这种交互 slash commands。

这时没有继续在错误方向上修修补补，而是先重新核对官方文档，再整篇重写，最后还顺势拆成两篇：一篇讲新手最该先掌握的 8 个高频命令，一篇讲完整命令清单。这个过程很能体现 Codex 的价值：先纠偏，再重构内容。

网站进入内容阶段后，很快暴露出一个真实前端问题：某篇文章标题太长，导致首页卡片布局失衡。这个问题看起来很小，但如果不处理，会直接影响首页观感。

修复方式不是简单缩短标题，而是调整卡片组件本身，让它支持更稳的换行、等高布局和可伸展摘要区域。这样以后再出现长标题，也不会继续把首页撑坏。

这个项目还有一个很实际的过程，就是首页文案多次迭代。比如重复的 Learn Codex、别扭的英文 slogan、偏内部口径的上线范围，这些都不是靠一开始就想对，而是边看边改、边体验边收敛。

这也是 Codex 在内容站里很实用的一点：你可以快速要求它改一小块文案、一段布局、一张卡片，而不用重新搭整页。

在页面和内容有了以后，网站继续补了 metadata、sitemap.xml、robots.txt、静态参数生成、相关推荐和上一篇下一篇等能力。这些功能不会像首页视觉那样显眼，但对教程站非常重要。

尤其是文章型网站，SEO 和内部链接结构不是上线后再想的事情，而应该尽早进入基础版本。

因为目标平台一开始就定成了 Vercel，所以项目没有走复杂部署路线，而是尽量保持 Next.js 原生兼容，配合环境变量生成站点 URL，保证 metadata 和 sitemap 在部署后能直接使用正式域名。

这里还有一个很实际的坑：一开始用了在线 Google 字体，后来在本地构建时因为字体请求失败而报错，最终改成了不依赖在线拉取的字体方案。这一步非常典型，说明部署准备不只是填配置，还包括把潜在不稳定依赖提前移除。

网站做好之后，再把本地仓库初始化、接远程、提交、推送到 GitHub。这个过程里也遇到过 SSH 权限不通的问题，最后切成 HTTPS 远程顺利推送。

这说明 Codex 的实战价值不只是写页面，它同样适合帮助你处理真实项目流程里的细节问题，例如初始化仓库、检查状态、修正忽略规则、整理首次提交。

第一，它能快速把模糊的需求收敛成可执行的网站结构。第二，它能持续推进实现，不会只停在建议层。第三，它能在做内容站这种多轮迭代任务里，不断根据反馈调整文案、结构和样式。

更重要的是，它不是只会写一段代码，而是能参与从计划、搭建、内容、排错、验证到上线准备的整条链路。这也是为什么这种项目特别适合作为 Codex 的实战案例。

如果你也想用 Codex 做一个内容型网站，最推荐的路径是先定主题和技术栈，再让它搭项目骨架，之后用统一内容数据结构驱动页面，最后逐步补 SEO、导航、文章和部署配置。

不要一开始就追求特别复杂的功能。先把一套结构清晰、内容可靠、可以部署的网站做出来，再慢慢扩展搜索、评论、订阅或更多专题，这是更稳的节奏。

做这种网站时，Codex 最强的地方不是替你一次性生成最终成品，而是它可以在每个阶段都接手一个明确任务：定结构、搭页面、补内容、改文案、修样式、查问题、做验证。

你把任务拆清楚，Codex 就能稳定推进。你把目标说模糊，它就会开始发散。这个项目本身，就是一个很好的证明。