ub-nuxt

UB Nuxt

概述

使用此技能，确保 Nuxt 开发与当前版本保持一致、类型安全并遵循框架原生模式。此技能面向最新稳定版 Nuxt：要求优先采用 app/ 源码布局、现代 Nuxt 运行时默认设置，以及当前的 Vue + TypeScript 模式，同时拒绝过时的目录指导。

根据检测到的项目和运行时实际情况进行实现，但框架指导应倾向于可向前兼容的迁移，而非默认保留旧版布局、过时方案或兼容层漂移。

按需加载参考资料

• 调整路由指导或跨技能编写规范时，阅读 ../ub-authoring/references/authoring-conventions.md。
• 阅读 references/nuxt-vue-patterns.md，了解架构、数据获取、路由、服务端和渲染方面的指导。
• 阅读 references/typescript-modern.md，了解严格 TypeScript 默认设置、类型模式和反模式检查。
• 阅读 references/ecosystem-preferences.md，了解现代软件包偏好、优先使用 VueUse 的启发式规则和替换矩阵。
• 阅读 references/nuxt-legacy-to-modern-migration.md，了解迁移差异、代码迁移映射和兼容性注意事项。

不适用场景

• 如果任务与 Nuxt 运行时、应用目录或 Nitro 无关，且仅涉及与框架无关的 Vue 组件或组合式函数逻辑，请勿使用此技能；根据 Vue 开发是否仍是首要关注点，改为共同加载 ub-vuejs 或交由其处理。
• 如果主要修改范围是纯 CSS 或 Tailwind 集成，而非 Nuxt 框架行为，请勿使用此技能；如果任务同时涉及这两方面，请共同加载相关样式技能。

核心工作流

1. 从 package.json、nuxt.config.*、锁文件和模块中检测 Nuxt 代际及当前工具链。始终检查 srcDir、future.compatibilityVersion 和 app/ 目录是否存在。
2. 编写代码前，先确定渲染和运行时模式（SSR、SSG、混合模式、边缘端／服务端）。
3. 对于重要或依赖版本的建议，比较官方指导、仓库实际情况和观察到的代码现状。
4. 如果权威来源、仓库实际情况或当前代码现状在重要建议上存在实质性分歧，请标明 OFFICIAL_CONFLICT。
5. 如果经过针对性研究后仍无法从官方来源确认某项重要声明，请标明 UNVERIFIED。
6. 使用 Composition API、<script setup lang="ts">、类型化组合式函数，并区分服务端与客户端，实现功能。
7. 优先采用 VueUse 以及 references/ecosystem-preferences.md 中的现代生态默认方案。
8. 应用 references/nuxt-vue-patterns.md 中的现代 Nuxt 运行时语义，以及 references/nuxt-legacy-to-modern-migration.md 中的迁移差异。
9. 拒绝过时的 Nuxt/Vue 模式，并用当前等效方案替换。
10. 修改后验证类型、lint/build 输出以及框架特定约束。

Nuxt 现代结构约定（硬性要求）

• 将所有应用源码放在 app/ 中：
  • app/pages、app/components、app/layouts、app/middleware、app/plugins
  • app/app.vue、app/app.config.ts
• 将运行时和项目根目录保留在仓库根目录：
  • server/、shared/、public/、modules/、nuxt.config.ts
• 如果明确配置了 srcDir，则遵循该配置，但仍须在此源码根目录内采用 Nuxt 现代结构语义。
• 将 future.compatibilityVersion 视为必需的检测信号：
  • 如果存在且低于当前稳定版本，请指出版本不匹配并提供修正指导。
• 不得在仓库根目录下搭建或建议使用旧版应用目录：
  • pages/、components/、layouts/、middleware/、plugins/。

实现规则

Nuxt 和 Vue

• 使用 Nuxt 原生基元（useAsyncData、useFetch、Nitro 服务端路由、插件、运行时配置），而不是绕过框架的自定义方案。
• 使用 Composition API 和组合式函数实现复用；除非明确要求，否则新代码避免使用 Options API。
• 明确服务端路由、服务端组合式函数和客户端组合式函数之间的数据所有权。
• 优先使用自动导入的 Nuxt 工具和组合式函数，以保持一致性。
• 生成或审查代码时，遵循现代 Nuxt 目录结构和运行时默认设置；不要生成旧版目录布局。

TypeScript

• 启用严格的 TypeScript 行为，避免在应用代码中使用 any。
• 为运行时配置、API 响应、组合式函数契约以及 emits/props 显式声明类型。
• 在类型稳定时优先使用类型推断；在边界处添加显式的导出类型或公共类型。
• 使用能够提升正确性的现代 TypeScript 特性（satisfies、const 断言、模板字面量类型、可辨识联合类型）。

生态系统与包选择

• 对于响应性、浏览器 API、传感器、生命周期封装和异步辅助功能，优先使用 VueUse，再考虑引入工具包。
• 选择 Nuxt 生态系统模块，以及维护活跃且 TypeScript 支持良好的库。
• 尽量减少依赖；如果 Nuxt/VueUse/标准平台 API 已能满足需求，就移除冗余包。
• Tailwind 的深入指导参见 .agents/skills/ub-tailwind/SKILL.md；Nuxt 任务中仅保留集成层面的 Tailwind 说明。

避免使用旧版模式的守则

• 不要搭建或推荐与现代 Nuxt 默认设置冲突的旧版目录约定。
• 新实现中不要引入 Vue 2 时代的模式（mixins、过滤器、类式组件装饰器）。
• 如果组合式函数或类型化 store 更清晰，不要默认使用临时的全局 store 或插件副作用。
• Nuxt 原生模式可用时，不要使用旧式路由或数据获取惯用法。
• 不要在根目录下的 pages/、components/、layouts/、middleware/ 或 plugins/ 中生成应用源文件。

版本与调研策略

• 以最新稳定版 Nuxt 为目标。
• 从 package.json、nuxt.config.* 和锁文件中检测项目实际使用的 Nuxt 版本。
• 使用网络搜索，根据 Nuxt 官方文档核实当前最佳实践、API 可用性和迁移指南。
• 判断当前项目中哪些方案能够安全落地时，将仓库实际情况视为实现标准。
• 将 Nuxt 官方文档视为面向未来的设计和便于迁移的模式的首选指导基准。
• 如果官方指导与仓库实际情况在重要建议上存在实质性分歧，请标注 OFFICIAL_CONFLICT，采用对仓库安全的方案，并说明迁移路径。
• 如果官方来源之间对重要建议存在分歧，也请标注 OFFICIAL_CONFLICT，不要悄然掩盖分歧。
• 如果经针对性调研后仍无法从官方来源确认某项重要主张，请标注 UNVERIFIED，或避免将其作为确定的指导。
• 仅在指导涉及重要、依赖版本或存在争议的内容时披露冲突和不确定性，不要将其用于琐碎修改。
• 如果项目安装的版本低于最新稳定版，请指出版本差距并建议升级路径。
• 如果存在 AGENTS.md 或同等指令文件，请检查宿主仓库中有关项目版本策略和工具的专属说明；不要假设其中包含本目录的默认设置。
• 生成的指导中不要硬编码版本号，使建议始终适用。

新鲜度审查

• 易变性：高
• 审查建议：在接触相关内容时以及定期维护期间审查；条件允许时按季度进行。
• 触发信号：Nuxt 发布周期变化、框架迁移指南更新、运行时默认值调整，或生态模块指南变更。
• 执行方式：仅供参考；新鲜度标记应优先提示审查，不应自动阻止无关的 Nuxt 工作。
• 稳定核心：Nuxt 原生基元、清晰的服务端／客户端边界，以及应用源代码与运行时根目录的分离，始终是稳定原则，即使具体方案不断演进。

输出要求

生成或审查代码时，始终包含：

1. 简短的环境检测说明（Nuxt 代际、Vue 版本系列、TS 严格模式状态）。
2. 源信息说明：检测到的项目版本、运行时布局，以及与最新稳定指南之间的任何重大差距。
3. 现代 Nuxt 结构合规说明（app/ 的位置、根目录运行时目录、srcDir 处理方式、future.compatibilityVersion 状态）。
4. 所选渲染／运行时策略，以及该策略适用的原因。
5. 添加依赖时的包选择理由（尤其是 VueUse 与其他方案的比较）。
6. 简要列出已移除或避免使用的旧模式。
7. 已执行的验证操作（在可用情况下包括类型检查／构建／测试／代码检查）。
8. 相关时的冲突说明：注明 OFFICIAL_CONFLICT 或 UNVERIFIED，并简要说明原因及其对实现的影响。

完成检查清单

• 编辑前已识别 Nuxt 模式和工具链。
• 符合现代 Nuxt 结构约定（app/ 用于应用源代码；根目录包含运行时目录）。
• 全程使用组合式优先和 Nuxt 原生模式。
• 明确声明 TypeScript 边界类型，并避免使用 any。
• 工具函数／响应式辅助函数优先使用 VueUse。
• 新增依赖均为现代、维护良好且有充分理由的依赖。
• 需要时将 Tailwind 相关细节交由 ub-tailwind 处理。
• 旧模式已替换，而非沿用。
• 如存在重大的官方来源冲突，或尚未验证的重要指南，相关时应明确披露。