SuperAPI AI 工具集

nuxt-best-practices

通用与其它

查看项目

更新于 10-15 22:10

技能介绍

用途:为 Nuxt 4 应用(当前 Nuxt 4.5,另含接近 EOL 的 3.x 说明)提供性能优化与架构规范,共 23 条规则、9 个类别,按影响优先级排序,用于指导自动重构和代码生成。

适用时机:编写新的 Nuxt 页面、组件或 composable;实现数据获取(useFetch、useAsyncData、4.5 的 enabled 选项);创建服务端路由与 API 端点;组织类型、composable 与自动导入;使用 Nuxt 模块与插件;配置渲染模式(SSR、SSG、SPA、4.5 实验性 SSR 流式渲染);使用布局、命名视图与 NuxtLink 预取(Nuxt 4.5 约定)。

规则类别与优先级:1 数据获取(CRITICAL,前缀 data-);2 自动导入与组织(CRITICAL,imports-);3 服务端与 API 路由(HIGH,server-);4 渲染模式(HIGH,rendering-);5 状态管理(MEDIUM-HIGH,state-);6 页面、布局与导航(MEDIUM,pages-);7 类型安全(MEDIUM,types-);8 模块与插件(LOW-MEDIUM,modules-);9 性能与部署(LOW,perf-)。

主要规则示例:数据获取要求使用 useFetch/useAsyncData 而非组件内裸 fetch,提供唯一 key,非关键数据用 lazy,在获取时转换数据,处理 error 与 pending,正确使用 refresh()/clear(),4.5+ 用 enabled 做条件获取;自动导入禁止在自动导入目录建 barrel 导出,组件名不重复文件夹前缀,类型放 app/types、shared/types、server/types,composable 只导出函数,composable 之间用直接导入;服务端用 getValidatedQuery/readValidatedBody 配合 Zod,加 defineRouteMeta,用 useRuntimeConfig 而非 process.env,用 createError,理解中间件顺序;渲染用 routeRules 按路由配置、混合渲染、构建期预渲染、ClientOnly、启用前先理解 4.5+ 实验性 SSR 流式渲染;状态用 useState 保证 SSR 安全、正确配置 Pinia、处理 hydration 不匹配、优先 computed;页面用 useLayout、name@view.vue 命名视图、在 NuxtLink 自定义插槽手动接预取(均 4.5+);类型禁止内联与 any,使用 #shared、~/、~~/ 路径,Zod 做运行时校验与类型推断,完整类型化 emits(声明 camelCase、监听 kebab-case);模块注意 nuxt.config 中顺序、区分运行时与构建期模块、正确使用 .client.ts/.server.ts 后缀、用 provide/inject;性能关注包体积分析、nuxt/image、字体加载策略、缓存头。

使用方式:阅读各规则文件(如 rules/data-use-fetch.md、rules/imports-no-barrel-autoimport.md、rules/_sections.md),每个文件含原因说明、错误代码示例、正确代码示例及 Nuxt 专属补充说明;完整展开版见 AGENTS.md。

限制:资料未提供安装命令、收费方式、平台支持与效果数据,暂未提供。