nuxt3

Nuxt 3 核心知识

完整参考：WebSocket 组合式函数、Nitro WebSocket 处理程序、Socket.IO 集成、插件模式、SSE 和房间管理模式，请参阅 advanced.md。

深入了解：使用 mcp__documentation__fetch_docs 并将 technology 设为 nuxt，获取全面的文档。

目录结构

目录	用途
pages/	基于文件的路由
components/	自动导入的组件
composables/	自动导入的组合式函数
server/	服务端路由和中间件
layouts/	页面布局
middleware/	路由中间件

页面组件

<script setup lang="ts">
// Auto-imports work: ref, computed, useFetch, etc.
const { data, pending } = await useFetch('/api/users')

definePageMeta({
  layout: 'admin',
  middleware: 'auth'
})
</script>

<template>
  <div v-if="pending">Loading...</div>
  <div v-else>{{ data }}</div>
</template>

数据获取

组合式函数	用途
useFetch	支持 SSR 的请求，带缓存
useAsyncData	自定义异步逻辑
$fetch	直接请求（不处理 SSR）
useLazyFetch	非阻塞请求

服务端路由

// server/api/users.get.ts
export default defineEventHandler(async (event) => {
  const query = getQuery(event)
  return await db.users.findMany()
})

// server/api/users.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  return await db.users.create(body)
})

主要特性

• 自动导入（组件、组合式函数、工具函数）
• 混合渲染（SSR、SSG、ISR、SPA）
• Nitro 服务端引擎
• 内置状态管理，使用 useState

不应使用此技能的情况

此技能适用于 Nuxt 3（Vue 元框架）。以下情况请勿使用：

• 不使用 Nuxt 的 Vue：改用 frontend-vue 技能
• Nuxt 2：查阅知识库，了解迁移到 Nuxt 3 的方法
• Next.js（React 元框架）：改用 nextjs-app-router 技能
• Remix（React 元框架）：改用 remix 技能
• SvelteKit：改用 sveltekit 技能
• Astro：改用 astro 技能
• 仅使用 Vite 的配置：使用搭配 Vite 配置的 frontend-vue

反模式

反模式	错误原因	正确做法
使用 $fetch 而不是 useFetch	不处理 SSR，数据不会缓存	使用 useFetch 进行支持 SSR 的请求
在 onMounted 中获取数据	仅限客户端，不支持 SSR	在 setup 中使用 useFetch/useAsyncData 获取数据
不使用自动导入	产生不必要的样板代码	依赖自动导入组件和组合式函数
在 public runtimeConfig 中存放密钥	会暴露给客户端，存在安全风险	使用仅限服务端的 runtimeConfig（不要使用 public）
忽略路由规则	错失性能优化机会	为各路由设置 prerender、swr 或 ssr 规则
没有 error.vue	错误体验不佳	创建 error.vue 进行全局错误处理

快速故障排除

问题	可能原因	解决方案
"useFetch is not defined"	自动导入未生效	检查是否已生成 .nuxt/tsconfig.json，然后重启开发服务器
SSR 时无法获取数据	使用了 $fetch 而不是 useFetch	将 $fetch 替换为 useFetch
"useState is not defined"	自动导入问题	使用 useState 组合式函数（Nuxt 3），确保已构建 .nuxt
生产环境中的 API 路由返回 404	未生成路由	检查 server/api/ 结构，然后重新构建
水合不匹配	服务端与客户端渲染结果不同	使用 ，确保状态一致
组件未自动导入	组件不在 components/ 目录中	将组件移至 components/，或在 nuxt.config 中配置

生产就绪

安全配置

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // Server-only (not exposed to client)
    dbPassword: process.env.DB_PASSWORD,

    // Exposed to client via useRuntimeConfig()
    public: {
      apiBase: process.env.API_BASE,
    },
  },
});

错误处理

<script setup lang="ts">
import type { NuxtError } from '#app';

const props = defineProps<{ error: NuxtError }>();
const handleError = () => clearError({ redirect: '/' });
</script>

<template>
  <div class="error-page">
    <h1>{{ error.statusCode }}</h1>
    <p>{{ error.message }}</p>
    <button @click="handleError">Go Home</button>
  </div>
</template>

性能

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },
    '/blog/**': { swr: 3600 }, // Stale-while-revalidate
    '/admin/**': { ssr: false }, // Client-only
  },
});

API 安全

// server/api/users.post.ts
export default defineEventHandler(async (event) => {
  // Validate input
  const body = await readValidatedBody(event, (body) => {
    return z.object({
      email: z.string().email(),
      name: z.string().min(2),
    }).parse(body);
  });

  // Auth check
  const session = await requireAuth(event);

  return await createUser(body);
});

测试

import { mountSuspended } from '@nuxt/test-utils/runtime';
import IndexPage from '~/pages/index.vue';

describe('Index Page', () => {
  it('renders correctly', async () => {
    const component = await mountSuspended(IndexPage);
    expect(component.text()).toContain('Welcome');
  });
});

监控指标

指标	目标
首字节时间	< 200ms
首次内容绘制	< 1.5s
水合时间	< 500ms
API 响应时间	< 100ms

检查清单

• 已配置安全标头
• 使用运行时配置存放密钥
• 错误处理（error.vue、插件）
• 路由规则（prerender、swr、ssr）
• 图像优化
• 延迟加载组件
• API 验证（Zod）
• 对 API 路由进行速率限制
• 为受保护路由配置身份验证中间件
• 使用 @nuxt/test-utils 进行端到端测试

参考文档

• 目录结构
• 数据获取模式