用 Codex 修改 Next.js 页面的一次实战流程

大家好，我是 Codex 中文网的站长宇哥。

为什么要写这篇实战

很多 Codex 教程只讲“你可以让 AI 改代码”，但真正落到项目里，新手最容易卡在三个地方：不知道怎么描述需求，不知道让 Codex 先看哪些文件，也不知道改完以后怎么验收。

这篇文章用一个 Next.js 内容站改造案例，把一次比较完整的 Codex 工作流拆开。目标不是炫技，而是让你看到：一个页面从普通 demo 变成像样的教程网站，中间应该怎样拆任务、怎样给约束、怎样验证结果。

案例背景是假设你有一个 Next.js 项目，想把它改造成“Codex 中文教程博客平台”。文章来自本地 content/posts，首页要有分类、文章卡片、热门文章、社群二维码、文章详情页和基础 SEO。第一版不做后台，不接数据库，先把静态内容站跑通。

开始前先做仓库检查

在让 Codex 改代码前，先确认仓库状态。不要在一堆未知改动上直接开工。

git status --short

如果已经有未提交内容，先看清楚哪些是你自己改的，哪些是上一轮工具生成的。Codex 可以在脏工作区里工作，但你要知道边界，否则后面 git diff 很难判断哪些变更该保留。

再看项目技术栈：

ls
find app components lib content -maxdepth 2 -type f

如果项目有 package.json，继续看脚本：

cat package.json

这一步的目的不是让你手动分析所有代码，而是给 Codex 一个正确起点：它应该先读路由、组件、内容读取层和构建脚本，而不是凭空写一套新架构。

第一个提示词：先让 Codex 读项目

不要第一句话就说“帮我做一个很酷的网站”。更好的开场是让 Codex 先建立上下文。

可以这样写：

先阅读这个 Next.js 项目的目录结构、app 路由、组件、content 目录和 package.json。
不要修改文件。
读完后告诉我当前项目如何渲染页面、文章数据从哪里来、有哪些可以复用的组件。

这个提示词有两个好处：

• 明确要求先读代码，不要马上改。
• 把 Codex 的输出限定到架构理解，方便你判断它有没有看懂项目。

如果 Codex 总结里把 Next.js App Router、content/posts、文章详情页、组件位置讲清楚了，再进入下一步。

第二个提示词：定义改造目标

接下来给它业务目标和验收标准。这里要具体，不要只说“好看一点”。

请把这个项目改造成 Codex 中文教程博客首页。
要求：
- 首页顶部有大轮播图，突出精选教程。
- 分类放在“最新文章”标题上方，点击分类后切换文章。
- 文章卡片更像教程网站，包含封面、分类角标、标题、摘要、阅读数和阅读按钮。
- 右侧栏先放社群二维码，再放热门文章。
- 文章详情页底部有分享和打赏区域。
- 阅读文章按钮在新窗口打开。
- 保持静态内容站，不引入数据库。
改完后运行质量检查和构建。

这个提示词里既有产品要求，也有技术边界。Codex 最怕的不是需求多，而是需求含糊。你越能说清楚“保留什么、不做什么、怎么验收”，它越容易给出稳定结果。

内容模型先定下来

教程站最重要的是内容模型。哪怕页面再漂亮，如果文章字段混乱，后面分类、RSS、Sitemap、搜索都会难维护。

本案例里每篇文章建议保留这些 frontmatter：

title
description
date
category
tags
cover
views
hot
featured

这些字段分别解决：

• 首页卡片展示。
• 分类页和标签页聚合。
• 文章详情页 SEO。
• 热门文章和精选轮播筛选。
• RSS 和 Sitemap 生成。
• 阅读数的基础展示。

如果你暂时没有真实阅读统计，可以先写死几百到几千的阅读数，等后面接数据库、日志分析或第三方统计时再替换。

让 Codex 写内容读取层

静态内容站的核心通常是一个内容读取模块。它负责从 content/posts 读取 MDX 或 Markdown 文件，解析 frontmatter，生成 slug，并提供常用查询函数。

你可以这样要求 Codex：

请实现一个内容读取层：
- 从 content/posts 读取 .md 和 .mdx 文件。
- 解析 frontmatter。
- 生成 slug、categorySlug、readingTime。
- 提供 getAllPosts、getPostBySlug、getFeaturedPosts、getHotPosts、getRelatedPosts。
- 不接数据库，保持构建时静态读取。

这类任务适合让 Codex 一次写完，因为边界清楚、输入输出明确。写完后你要检查两件事：解析是否足够稳，页面调用是否统一走这层 API。不要让不同页面各自读文件，否则后期维护会很乱。

页面改造顺序

建议按这个顺序让 Codex 改：

• 先改首页结构：轮播、分类、文章列表、右侧栏。
• 再改文章详情页：标题、摘要、正文、相关文章、分享、打赏。
• 再补分类页、标签页、搜索页。
• 最后补 RSS、Sitemap、robots 和自动发文脚本。

这样做的原因很简单：首页和文章详情是内容站主链路，先跑通主链路，再补周边页面。不要一开始就把所有页面、所有特效、所有自动化都塞进去。

首页改造完成后，建议你用肉眼重点看这些地方：

• 首屏是否直接像教程站，而不是营销落地页。
• 分类切换是否明确，当前分类状态是否清楚。
• 文章卡片是否能快速扫读标题、摘要、分类和阅读数。
• 右侧栏是否服务转化，比如社群二维码、热门教程。
• 移动端是否没有文字溢出和按钮挤压。

文章详情页要补哪些功能

教程网站的文章详情页不能只是标题加正文。至少要有这些模块：

• 标题、描述、分类、日期、阅读数。
• 正文内容。
• 相关文章。
• 分享功能。
• 打赏功能。
• 加入社群入口。

分享功能可以先实现为：

• 生成海报：前端生成一张包含标题、描述、站点名和二维码的图片。
• 分享微信：打开一个新页面，展示二维码，让用户扫码分享。
• 分享微博：打开微博分享 URL。
• 分享 QQ：打开 QQ 分享 URL。

微信网页分享在普通网站里不能像 App 一样直接调起微信好友列表，所以“点击后打开扫码页”是更现实的实现。微博和 QQ 则可以走它们的网页分享地址，新窗口打开。

给 Codex 的验证提示词

改完代码后，不要只听 Codex 说“完成了”。让它跑检查。

请运行项目已有的质量检查和构建命令。
如果失败，先根据错误修复，再重新运行。
最后告诉我改了哪些文件、验证结果是什么。

对于 Next.js 项目，常见命令可能是：

pnpm run quality:check
pnpm run build

如果项目还没有质量检查脚本，可以先加一个轻量脚本，检查文章 frontmatter、固定开场白、阅读数范围、FAQ 和正文长度。内容站很容易因为一篇文章格式写错导致页面构建失败，这类检查很值得做。

视觉验收怎么做

前端页面不能只靠构建通过。构建通过说明代码能打包，不代表页面好用。

建议至少检查：

• 桌面端首页。
• 移动端首页。
• 一篇文章详情页。
• 分类切换。
• 分享弹窗或新页面。
• 社群二维码和打赏二维码是否加载。

如果 Codex 有浏览器控制能力，可以让它打开本地开发服务器截图检查。如果没有，你也可以自己打开页面，然后把截图发给 Codex，让它根据截图继续调。

给截图反馈时要具体：

分类区域太靠下，希望放到“最新文章”标题上方。
文章缩略图右下角加分类角标。
右侧热门文章上方放社群二维码。
底部再放一个加入社群入口。

这种反馈比“感觉不太像教程站”更容易被执行。

内容质量要单独要求

搭好网站只是第一步，文章如果像 demo，用户还是不会停留。你要明确要求 Codex 按教程标准写文章，而不是写短提纲。

可以写：

请把现有 demo 文章补充成正式教程。
要求：
- 每篇文章开头固定写：大家好，我是 Codex 中文网的站长宇哥。
- 保留 frontmatter。
- 正文包含适合人群、准备工作、步骤、检查命令、常见问题和总结。
- 尽量参考 OpenAI 官方 Codex 文档口径。
- 不要写空泛营销话术，不要像 AI 生成充数。

如果这个规则以后会长期使用，就不要只写在提示词里。可以放到固定规则文件里，例如 content/rules/article-rules.json，再让自动发文脚本和质量检查脚本都读取它。这样以后每次生成文章，都能自动套用同一套规则。

一次实战后的复盘清单

项目完成后，建议做一次复盘：

• 内容读取层是否集中，页面有没有重复读文件。
• 文章 frontmatter 是否统一。
• 新增功能是否有质量检查覆盖。
• 构建产物是否生成 RSS 和 Sitemap。
• 所有图片路径是否来自 public/images。
• 分享和打赏功能是否在文章详情页可见。
• 外链和分享链接是否新窗口打开。
• 移动端是否可读。

复盘不是形式主义。它能帮你把“这次能跑”变成“下次还能稳定扩展”。

常见问题 FAQ

这种内容站第一版要不要接数据库？

不建议。第一版用本地 Markdown 或 MDX 更快，部署也简单。等你真的需要投稿、审核、用户权限、会员内容或后台编辑，再考虑数据库和 CMS。

能不能一次让 Codex 做完所有功能？

可以，但要分阶段验收。你可以在一个大任务里列出全部目标，但执行时仍然要求它先读代码、再改主链路、再补周边功能、最后验证。否则失败时很难定位。

Next.js 页面改完后只跑 build 够吗？

不够。build 只能证明能打包。教程站还要看内容质量、移动端布局、图片加载、分类切换、详情页渲染、RSS 和 Sitemap。至少要做一次浏览器预览。

Codex 写的文章怎么避免像 AI 充数？

给它明确结构和真实场景：适合谁、解决什么问题、准备工作、操作步骤、检查命令、常见问题、官方文档链接。不要只要求“写长一点”，长度不是质量，具体可执行才是质量。

参考官方文档

这个案例会用到 Codex 的安装、CLI、配置和自定义能力，建议配合官方文档一起看：

• Codex Quickstart
• Codex CLI 文档
• Codex 配置基础
• Codex MCP 文档

总结

用 Codex 改 Next.js 页面，关键不是把提示词写得花，而是把工程步骤拆清楚：先读项目，再定义目标，再改内容模型，再做页面，再补 SEO 和自动化，最后运行检查和构建。

当你把“需求、约束、验收方式”说清楚，Codex 就更像一个能协作的工程搭档。它负责快速读代码和落地修改，你负责把产品方向、内容标准和最终验收把住。这样的配合，才适合长期做一个教程网站。