nuxt

Nuxt 4+ 开发

针对 Nuxt 4+ 项目（v4.3+）的渐进式指南，包含最新模式和约定。

使用场景

适用于以下工作：

• 服务器路由（API 端点、服务器中间件、服务器工具）
• 基于文件的路由（页面、布局、路由组）
• Nuxt 中间件（路由守卫、导航）
• Nuxt 插件（应用扩展）
• Nuxt 特有功能（自动导入、层、模块）

可用指南

根据当前工作读取特定文件：

• references/server.md - API 路由、服务器中间件、验证（Zod）、WebSocket、SSE
• references/routing.md - 基于文件的路由、路由组、类型化路由、definePage
• references/middleware-plugins.md - 路由中间件、插件、应用生命周期
• references/nuxt-composables.md - Nuxt 组合式函数（useRequestURL、useFetch、导航）
• references/nuxt-components.md - NuxtLink、NuxtImg、NuxtTime（优先于 HTML 元素）
• references/nuxt-config.md - 配置、模块、自动导入、层

关于 Vue 组合式函数： 参见 vue 技能的 composables.md（VueUse、Composition API 模式）
关于 UI 组件： 使用 nuxt-ui 技能
关于数据库/存储： 使用 nuxthub 技能
关于内容驱动网站： 使用 nuxt-content 技能
关于创建模块： 使用 nuxt-modules 技能
关于项目脚手架/CI： 使用 ts-library 技能

加载文件

根据任务考虑加载以下参考文件：

• [ ] references/server.md - 如果创建 API 端点或服务器中间件
• [ ] references/routing.md - 如果设置页面、布局或路由组
• [ ] references/nuxt-composables.md - 如果使用 Nuxt 组合式函数（useFetch、useRequestURL 等）
• [ ] references/middleware-plugins.md - 如果处理中间件或插件
• [ ] references/nuxt-components.md - 如果使用 Nuxt 组件（NuxtLink、NuxtImg 等）
• [ ] references/nuxt-config.md - 如果编辑 nuxt.config.ts
• [ ] references/project-setup.md - 如果设置 CI/ESLint/构建工具

不要一次性加载所有文件。 只加载与当前任务相关的文件。

快速开始

// server/api/hello.get.ts
import { z } from 'zod'

export default defineEventHandler(async (event) => {
  const { name } = await getValidatedQuery(event, z.object({
    name: z.string().default('world'),
  }).parse)
  return { message: `Hello ${name}` }
})

Nuxt 4 与旧版本对比

你正在使用 Nuxt 4+。 主要区别：

旧版（Nuxt 2/3）	新版（Nuxt 4）
<Nuxt />	<NuxtPage />
context.params	getRouterParam(event, 'name')
window.origin	useRequestURL().origin
字符串路由	类型化路由，带路由名称
独立布局/	父路由配合 <slot>

如果不确定 Nuxt 4 模式，请先阅读相关指南文件。

最新文档

何时获取最新文档：

• 此处未涵盖的新 Nuxt 4 功能
• 模块特定配置
• 破坏性变更或弃用
• 高级用例

官方来源：

• Nuxt：https://nuxt.com/docs
• h3（服务器引擎）：https://v1.h3.dev/
• Nitro：https://nitro.build/

Token 效率

主技能：约 300 tokens。每个子文件：约 800-1500 tokens。仅加载与当前任务相关的文件。