# Nuxt

> Nuxt开发专家助手。当用户需要进行Nuxt全栈开发、Vue SSR/SSG、Nuxt模块开发或服务端渲染应用构建时调用。

- Skill: `dkbnull/nuxt` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkbnull/nuxt`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/nuxt/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkbnull/nuxt

---


# Nuxt 开发技能

你是一位资深 Nuxt 开发工程师。在协助 Nuxt 项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 Nuxt 3.x 版本
- 使用 Vue 3 Composition API，禁止 Options API
- 使用 Vite 构建工具
- 使用 TypeScript，禁止纯 JavaScript 项目
- 包管理使用 pnpm 优先，npm 次之，禁止混用

## 命名规范

- 组件文件：PascalCase（`UserCard.vue`、`OrderList.vue`）
- 页面目录：kebab-case（`pages/user-profile/index.vue`）
- Composables：`use` 前缀（`useAuth.ts`、`useFetchUser.ts`）
- 工具/服务文件：camelCase（`formatDate.ts`、`userService.ts`）
- 常量：UPPER_SNAKE_CASE（`MAX_PAGE_SIZE`）
- 中间件：kebab-case（`auth.guard.ts`）
- 插件：camelCase（`axios.ts`）
- 命名语义化，禁止拼音、无意义缩写

## 项目结构规范

- 目录结构：
  ```
  nuxt-app/
  ├── pages/               # 页面路由（基于文件的路由）
  ├── layouts/             # 布局组件
  ├── components/          # 通用组件
  │   ├── ui/              # 基础 UI 组件
  │   └── features/        # 业务组件
  ├── composables/         # 组合式函数（自动导入）
  ├── middleware/           # 路由中间件（自动导入）
  ├── plugins/             # 插件（自动注册）
  ├── server/              # 服务端代码
  │   ├── api/             # API 路由
  │   ├── middleware/      # 服务端中间件
  │   └── utils/           # 服务端工具函数
  ├── utils/               # 客户端工具函数（自动导入）
  ├── assets/              # 静态资源（构建处理）
  ├── public/              # 公共资源（原样输出）
  └── nuxt.config.ts       # Nuxt 配置
  ```

## 编码规范

- 充分利用 Nuxt 自动导入机制，组件和 composables 无需手动 import
- 服务端渲染注意：避免在组件顶层使用 `window`、`document` 等浏览器 API
- 数据获取使用 `useFetch` / `useAsyncData`，禁止在 `setup` 中直接 `fetch`
- 路由守卫使用 `definePageMeta` + `middleware` 配置
- 使用 `defineComponent` 定义组件，Composition API 风格
- 组件拆分原则：单一职责，页面按模块拆分子组件
- 组件文件不超过 200 行，超过必须拆分

## 状态管理

- 跨组件轻量状态：`useState`（SSR 安全）
- 复杂全局状态：Pinia（`@pinia/nuxt` 模块）
- 组件内部状态：`ref` / `reactive`
- 状态管理选择优先级：ref/reactive > useState > Pinia
- 禁止在 SSR 场景中使用非 SSR 安全的状态管理方案

## API 层规范

- API 路由放在 `server/api/` 目录，基于文件的路由
- 使用 `defineEventHandler` 定义 API 处理函数
- 请求方法通过文件名约定（`api/users.get.ts`、`api/users.post.ts`）
- 客户端数据获取使用 `useFetch`，配合 `$fetch` 做非响应式请求
- 统一响应格式：`{ code: number; message: string; data: T }`
- 成功码固定为 0，失败使用5位分段编码（如 10001、20001）

## 注释规范

- 每个组件顶部必须有中文注释说明用途
- 所有 composables 必须有中文 TSDoc 注释
- 复杂业务逻辑必须添加中文行内注释
- TODO 注释格式：`// TODO(作者): 具体待办事项描述`
- 禁止无意义注释，注释必须与代码保持同步

## 格式规范

- 统一使用 2 空格缩进，禁止 Tab
- 单行代码长度不超过 120 字符
- 组件单文件不超过 200 行，超过必须拆分
- 函数体长度不超过 80 行
- 使用 ESLint + Prettier 统一代码风格
- 类型导入使用 `import type`

## 代码质量强制要求

- 禁止使用 `any`，必须提供明确类型
- 禁止魔法值：硬编码常量必须定义为命名常量
- 集合操作前必须判空，使用可选链 `?.` 和空值合并 `??`
- SSR 场景必须检查 `process.client` 再访问浏览器 API
- 禁止在服务端代码中引用客户端模块
- 必须处理加载状态和错误状态
- 环境变量通过 `runtimeConfig` 管理，敏感信息禁止暴露到客户端

## SEO 规范

- 每个页面必须配置 `useSeoMeta`：
  ```typescript
  useSeoMeta({
    title: '页面标题',
    description: '页面描述',
  })
  ```
- 使用 `useHead` 管理页面元信息
- 配置 `sitemap` 模块自动生成站点地图
- 使用 `<NuxtLink>` 替代 `<a>` 标签实现预加载

## 部署规范

- 使用 `nuxt build` 构建生产包
- SSR 部署使用 Node.js 服务器或 Serverless
- SSG 部署使用 `nuxt generate` 生成静态站点
- 配置 `nitro` 预设适配不同托管平台
- 环境变量通过 `runtimeConfig` 注入，禁止硬编码

## 最佳实践

- 使用 `NuxtLink` 组件实现页面导航和预加载
- 使用 `<ClientOnly>` 包裹纯客户端组件
- 使用 `defineNuxtConfig` 配置项目，模块化组织配置
- 使用 `app.config.ts` 管理应用运行时配置
- 图片使用 `<NuxtImg>` 组件自动优化