Vue 与 Nuxt 完整改版实战

本案例以“为 Nuxt 内容站新增带筛选和详情入口的课程列表页”为例。重点是完整交付链路，不绑定某个 Nuxt 小版本。

教程目标

让 Codex完成需求澄清、现状审计、组件设计、实现、测试、SSR/构建验证和 diff 复审。

第 1 步：只读认识项目

请只读分析当前 Vue/Nuxt 项目，不要修改文件。

确认：
1. Vue、Nuxt、Node 和包管理器版本。
2. pages、components、composables、server、tests 的实际结构。
3. 路由、数据获取、状态管理和样式方案。
4. lint、typecheck、test、build 的真实命令。
5. SSR、SSG 或纯客户端模式，以及本需求的影响。

不要把 Nuxt 2、Nuxt 3/4 的写法混用；以项目锁文件和官方迁移文档为准。

第 2 步：固定需求与验收

任务目标：新增课程列表页，支持关键词和难度筛选，点击卡片进入现有详情页。

范围：优先复用现有布局、组件、数据层和设计变量。
禁止：不改鉴权、支付、数据库结构，不升级依赖，不重构无关页面。

验收：
1. 首次 SSR 输出包含课程列表。
2. 筛选状态可通过 URL 查询参数恢复。
3. 空结果、加载和错误状态明确。
4. 键盘可以完成筛选和进入详情。
5. 类型检查、测试和构建通过。

第 3 步：先设计文件变化

要求 Codex列出将修改/新增的文件、每个文件职责、数据流和回滚方法。筛选逻辑放在可测试的 composable 或纯函数中，页面只协调状态和渲染。

第 4 步：分两轮实现

第一轮完成数据与筛选逻辑并补单元测试；第二轮完成页面、无障碍标签和响应式样式。每轮都先跑最小检查并展示 diff。

先实现筛选数据流和测试，不写大段页面样式。
确认通过后，再实现 UI。不要使用仅在浏览器存在的对象破坏 SSR。

第 5 步：检查 Nuxt 特有风险

• useFetch / useAsyncData 的 key 与服务端、客户端一致。
• 不在服务端直接访问 window、document、localStorage。
• 查询参数序列化稳定，前进后退可以恢复状态。
• 列表 key 使用稳定业务 ID，不使用数组索引。
• 客户端 hydration 不出现内容不一致警告。

第 6 步：完整验证

请按项目真实脚本运行 lint、typecheck、相关测试和 production build。
启动生产预览后，验证默认列表、筛选、刷新恢复、空状态、错误状态和详情跳转。
最后审查完整 diff，列出未验证的真实后端场景。

常见失败分支

• 开发模式正常、构建失败：检查服务端执行路径和类型错误。
• 刷新后筛选丢失：让 URL 成为可恢复状态来源。
• hydration mismatch：找出服务端与客户端初始值差异。
• 页面能用但不可键盘操作：改用语义化表单控件和可见焦点。
• 为小功能升级全套 Nuxt：回退无关依赖变化，另开升级任务。

验收结果

1. 实现复用项目现有架构，没有混用版本 API。
2. 筛选逻辑有测试，页面覆盖加载、空、错和成功状态。
3. URL、SSR 和 hydration 行为已验证。
4. lint、类型检查、测试和生产构建有真实结果。
5. 完整 diff 没有鉴权、支付、数据库或无关重构。

下一篇看：Codex × Playwright 端到端测试实战。