web-meta-framework-nuxt

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Nuxt Framework Patterns

Nuxt 框架模式

Quick Guide: Use
useFetch
for API calls in components (SSR-safe),
useAsyncData
for custom data sources or parallel fetches. Create server routes in
server/api/
. Auto-imports handle composables and components automatically. Use
useState
for SSR-friendly shared state. Data is a
shallowRef
by default -- use
deep: true
if you need deep reactivity.

<critical_requirements>
快速指南: 在组件中使用
useFetch
进行 API 调用(支持SSR),
useAsyncData
用于自定义数据源或并行请求。在
server/api/
目录下创建服务端路由。自动导入功能会自动处理组合式函数和组件。使用
useState
实现支持SSR的共享状态。默认情况下数据是
shallowRef
——如果需要深度响应式,请使用
deep: true
。

<critical_requirements>

CRITICAL: Before Using This Skill

重要提示:使用此技能前须知

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,
import type
, named constants)
(You MUST use
useFetch
or
useAsyncData
for data fetching in components -- NEVER raw
$fetch
in setup which causes double-fetching)
(You MUST use
server/api/
for API routes -- handlers export default with
defineEventHandler()
)
(You MUST use
definePageMeta
to attach middleware and configure page behavior -- it is a macro, values must be statically analyzable)
(You MUST use
useHead
or
useSeoMeta
for SEO metadata -- never manual
<head>
tags)
(You MUST ensure
useState
values are JSON-serializable for SSR hydration -- no functions, classes, or Symbols)
</critical_requirements>

Auto-detection: Nuxt, nuxt.config.ts, useFetch, useAsyncData, useState, defineEventHandler, definePageMeta, defineNuxtRouteMiddleware, NuxtLayout, NuxtPage, NuxtLink, navigateTo, server/api, pages/, layouts/, middleware/, composables/, useHead, useSeoMeta, app/ directory
When to use:
  • Building Vue 3 applications with file-based routing and SSR/SSG
  • Creating full-stack applications with server routes in the same project
  • Implementing data fetching that works seamlessly across server and client
  • Building SEO-optimized pages with automatic metadata handling
  • Leveraging auto-imports for composables and components
Key patterns covered:
  • File-based routing (pages/, dynamic routes, catch-all routes)
  • Data fetching (useFetch, useAsyncData, $fetch)
  • Server routes (server/api/, defineEventHandler)
  • Shared state (useState composable)
  • Route middleware (defineNuxtRouteMiddleware, navigateTo)
  • Layouts (layouts/, NuxtLayout, setPageLayout)
  • SEO (useHead, useSeoMeta)
  • Plugins (plugins/, defineNuxtPlugin)
  • Error handling (NuxtErrorBoundary, createError, showError)
  • Auto-imports (composables, components, utils)
When NOT to use:
  • Simple SPAs without SSR needs (consider Vue + Vite directly)
  • Static documentation sites without server logic (consider a static-site generator)

<philosophy>
所有代码必须遵循 CLAUDE.md 中的项目约定(短横线命名法、命名导出、导入排序、
import type
、命名常量)
(在组件中进行数据获取时,必须使用
useFetch
或
useAsyncData
——绝对不要在 setup 中直接使用
$fetch
,这会导致重复请求)
(必须使用
server/api/
来创建 API 路由——处理器需通过
defineEventHandler()
导出默认函数)
(必须使用
definePageMeta
来绑定中间件并配置页面行为——这是一个宏,其值必须可被静态分析)
(必须使用
useHead
或
useSeoMeta
来设置 SEO 元数据——绝不要手动编写
<head>
标签)
(必须确保
useState
的值可被 JSON 序列化,以支持 SSR 水合——不能包含函数、类或 Symbol)
</critical_requirements>

自动检测项: Nuxt、nuxt.config.ts、useFetch、useAsyncData、useState、defineEventHandler、definePageMeta、defineNuxtRouteMiddleware、NuxtLayout、NuxtPage、NuxtLink、navigateTo、server/api、pages/、layouts/、middleware/、composables/、useHead、useSeoMeta、app/ 目录
适用场景:
  • 使用基于文件的路由和SSR/SSG构建 Vue 3 应用
  • 在同一项目中创建带有服务端路由的全栈应用
  • 实现可在服务端和客户端无缝运行的数据获取逻辑
  • 构建具备自动元数据处理的 SEO 优化页面
  • 利用自动导入功能使用组合式函数和组件
涵盖的核心模式:
  • 基于文件的路由(pages/、动态路由、通配符路由)
  • 数据获取(useFetch、useAsyncData、$fetch)
  • 服务端路由(server/api/、defineEventHandler)
  • 共享状态(useState 组合式函数)
  • 路由中间件(defineNuxtRouteMiddleware、navigateTo)
  • 布局(layouts/、NuxtLayout、setPageLayout)
  • SEO(useHead、useSeoMeta)
  • 插件(plugins/、defineNuxtPlugin)
  • 错误处理(NuxtErrorBoundary、createError、showError)
  • 自动导入(组合式函数、组件、工具函数)
不适用场景:
  • 无需SSR的简单SPA(可直接考虑 Vue + Vite)
  • 无服务端逻辑的静态文档站点(可考虑静态站点生成器)

<philosophy>

Philosophy

设计理念

Nuxt is a meta-framework for Vue 3 that provides file-based routing, automatic code splitting, server-side rendering, and a powerful data-fetching system. Built on Nitro server engine, it enables full-stack development with API routes colocated with your frontend.
Core Principles:
  1. Universal rendering by default -- Pages render on server first, then hydrate on client
  2. Auto-imports everywhere -- Composables, components, and utilities are automatically available
  3. File-based conventions -- Directories define behavior (pages/, server/, layouts/, middleware/)
  4. SSR-safe data fetching -- Composables prevent double-fetching between server and client
  5. Zero-config TypeScript -- Full type safety with automatic type generation
  6. Shallow reactivity for performance --
    data
    from
    useFetch
    /
    useAsyncData
    is a
    shallowRef
    by default
</philosophy>
<patterns>
Nuxt 是一款 Vue 3 元框架,提供基于文件的路由、自动代码分割、服务端渲染以及强大的数据获取系统。它构建于 Nitro 服务引擎之上,支持将 API 路由与前端代码放在同一项目中,实现全栈开发。
核心原则:
  1. 默认支持通用渲染——页面先在服务端渲染,然后在客户端进行水合
  2. 全局自动导入——组合式函数、组件和工具函数可直接使用
  3. 基于文件的约定——目录结构定义功能(pages/、server/、layouts/、middleware/)
  4. 支持SSR的数据获取——组合式函数避免服务端与客户端之间的重复请求
  5. 零配置 TypeScript——通过自动类型生成实现完整的类型安全
  6. 浅响应式提升性能——
    useFetch
    /
    useAsyncData
    返回的
    data
    默认是
    shallowRef
</philosophy>
<patterns>

Core Patterns

核心模式

Pattern 1: File-Based Routing

模式1:基于文件的路由

File names in
pages/
become URL paths. Dynamic segments use bracket syntax.
FileURLDescription
pages/index.vue
/
Home page
pages/about.vue
/about
Static route
pages/blog/[slug].vue
/blog/:slug
Dynamic parameter
pages/users/[...slug].vue
/users/*
Catch-all route
pages/posts/[[id]].vue
/posts
or
/posts/:id
Optional parameter
vue
<!-- pages/blog/[slug].vue -->
<script setup lang="ts">
const route = useRoute();
const slug = route.params.slug as string;
const { data: post, error } = await useFetch(`/api/posts/${slug}`);

if (error.value) {
  throw createError({ statusCode: 404, statusMessage: "Post not found" });
}
</script>
Why good: File names map to URLs, bracket syntax for dynamic params, createError triggers error page
See examples/core.md for complete page examples with layouts and middleware.

pages/
目录下的文件名对应 URL 路径。动态路由段使用括号语法。
文件路径URL 路径描述
pages/index.vue
/
首页
pages/about.vue
/about
静态路由
pages/blog/[slug].vue
/blog/:slug
动态参数路由
pages/users/[...slug].vue
/users/*
通配符路由
pages/posts/[[id]].vue
/posts
或
/posts/:id
可选参数路由
vue
<!-- pages/blog/[slug].vue -->
<script setup lang="ts">
const route = useRoute();
const slug = route.params.slug as string;
const { data: post, error } = await useFetch(`/api/posts/${slug}`);

if (error.value) {
  throw createError({ statusCode: 404, statusMessage: "文章未找到" });
}
</script>
优势: 文件名与URL直接映射,括号语法定义动态参数,createError可触发错误页面
完整的页面示例(包含布局和中间件)请查看 examples/core.md。

Pattern 2: Data Fetching (useFetch / useAsyncData)

模式2:数据获取(useFetch / useAsyncData)

useFetch
wraps
useAsyncData
+
$fetch
. It prevents double-fetching by transferring server data to client during hydration. Data is a
shallowRef
-- replace the whole object to trigger reactivity, or use
deep: true
.
typescript
// Simple fetch -- URL is cache key
const { data, error, status, refresh, clear } = await useFetch("/api/users");

// With reactive query params and auto-refetch
const page = ref(1);
const { data: users } = await useFetch("/api/users", {
  query: { page, limit: 20 },
  watch: [page],
});

// POST with immediate: false for user-triggered actions
const { execute, status } = useFetch("/api/users", {
  method: "POST",
  body: form,
  immediate: false,
  watch: false,
});
Use
useAsyncData
when combining multiple fetches or using non-HTTP sources:
typescript
const { data } = await useAsyncData("dashboard", async () => {
  const [users, stats] = await Promise.all([
    $fetch("/api/users"),
    $fetch("/api/stats"),
  ]);
  return { users, stats };
});
Critical:
$fetch
in
<script setup>
(outside useFetch/useAsyncData) runs on both server and client, causing double-fetching. Always wrap in a composable.
See examples/data-fetching.md for typed responses, transforms, lazy loading, and server-only fetch patterns.

useFetch
封装了
useAsyncData
+
$fetch
。它通过在水合过程中将服务端数据传递到客户端,避免重复请求。返回的
data
是
shallowRef
——如需触发响应式,需替换整个对象,或使用
deep: true
。
typescript
// 简单请求——URL作为缓存键
const { data, error, status, refresh, clear } = await useFetch("/api/users");

// 带有响应式查询参数和自动重新请求
const page = ref(1);
const { data: users } = await useFetch("/api/users", {
  query: { page, limit: 20 },
  watch: [page],
});

// POST 请求,immediate: false 用于用户触发的操作
const { execute, status } = useFetch("/api/users", {
  method: "POST",
  body: form,
  immediate: false,
  watch: false,
});
当需要组合多个请求或使用非HTTP数据源时,使用
useAsyncData
:
typescript
const { data } = await useAsyncData("dashboard", async () => {
  const [users, stats] = await Promise.all([
    $fetch("/api/users"),
    $fetch("/api/stats"),
  ]);
  return { users, stats };
});
重要提示: 在
<script setup>
中直接使用
$fetch
(未包裹在useFetch/useAsyncData中)会同时在服务端和客户端执行,导致重复请求。务必将其包裹在组合式函数中。
类型化响应、数据转换、懒加载以及服务端专属请求模式请查看 examples/data-fetching.md。

Pattern 3: Server Routes

模式3:服务端路由

Server routes live in
server/api/
(prefixed with
/api
) or
server/routes/
(no prefix). File suffix restricts HTTP method.
typescript
// server/api/users.get.ts
export default defineEventHandler(async (event) => {
  const query = getQuery(event);
  const page = Number(query.page) || 1;
  return db.users.findMany({ skip: (page - 1) * 20, take: 20 });
});

// server/api/users.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event);
  // Validate body with Zod or similar
  setResponseStatus(event, 201);
  return db.users.create({ data: body });
});
PatternFileURL
GET
server/api/users.get.ts
GET /api/users
POST
server/api/users.post.ts
POST /api/users
Dynamic
server/api/users/[id].ts
/api/users/:id
Catch-all
server/api/[...path].ts
/api/*
No prefix
server/routes/health.ts
/health
See examples/server-routes.md for validation, error handling, server middleware, and CRUD patterns.

服务端路由位于
server/api/
(自动添加
/api
前缀)或
server/routes/
(无前缀)。文件后缀限制HTTP请求方法。
typescript
// server/api/users.get.ts
export default defineEventHandler(async (event) => {
  const query = getQuery(event);
  const page = Number(query.page) || 1;
  return db.users.findMany({ skip: (page - 1) * 20, take: 20 });
});

// server/api/users.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event);
  // 使用Zod或类似工具验证请求体
  setResponseStatus(event, 201);
  return db.users.create({ data: body });
});
模式文件路径URL 路径
GET 请求
server/api/users.get.ts
GET /api/users
POST 请求
server/api/users.post.ts
POST /api/users
动态路由
server/api/users/[id].ts
/api/users/:id
通配符路由
server/api/[...path].ts
/api/*
无前缀路由
server/routes/health.ts
/health
验证、错误处理、服务端中间件以及CRUD模式请查看 examples/server-routes.md。

Pattern 4: useState for Shared State

模式4:使用 useState 管理共享状态

useState
is an SSR-friendly composable for shared reactive state. Values transfer from server to client during hydration and must be JSON-serializable.
typescript
// composables/use-user.ts
export function useUser() {
  const user = useState<User | null>("user", () => null);
  const isLoggedIn = computed(() => user.value !== null);

  async function login(credentials: { email: string; password: string }) {
    user.value = await $fetch<User>("/api/auth/login", {
      method: "POST",
      body: credentials,
    });
  }

  return { user: readonly(user), isLoggedIn, login };
}
Key constraints: Values must be JSON-serializable (no functions, classes). Key ensures singleton sharing across components. Wrap mutations in composable functions.
See examples/state-management.md for cart state, UI state, cookie persistence, and server-initialized patterns.

useState
是支持SSR的组合式函数,用于管理共享响应式状态。其值会在水合过程中从服务端传递到客户端,必须可被JSON序列化。
typescript
// composables/use-user.ts
export function useUser() {
  const user = useState<User | null>("user", () => null);
  const isLoggedIn = computed(() => user.value !== null);

  async function login(credentials: { email: string; password: string }) {
    user.value = await $fetch<User>("/api/auth/login", {
      method: "POST",
      body: credentials,
    });
  }

  return { user: readonly(user), isLoggedIn, login };
}
关键约束: 值必须可被JSON序列化(不能包含函数、类)。键确保状态在组件间是单例。请将状态修改逻辑封装在组合式函数中。
购物车状态、UI状态、Cookie持久化以及服务端初始化模式请查看 examples/state-management.md。

Pattern 5: Route Middleware

模式5:路由中间件

Middleware runs before navigation. Use for auth, authorization, and redirects.
typescript
// middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
  const { isLoggedIn } = useUser();
  if (!isLoggedIn.value) {
    return navigateTo(`/login?redirect=${encodeURIComponent(to.fullPath)}`);
  }
});
TypeFile PatternBehavior
Named
middleware/auth.ts
Opt-in via definePageMeta
Global
middleware/auth.global.ts
Runs on every navigation
InlineFunction in definePageMetaPage-specific logic
Attach via
definePageMeta({ middleware: "auth" })
or
definePageMeta({ middleware: ["auth", "admin"] })
.
Critical: Use
to
and
from
parameters -- never
useRoute()
in middleware (may have stale values).
See examples/middleware.md for role-based auth, feature flags, guest guards, and global middleware patterns.

中间件在导航前执行,用于权限验证、授权和重定向。
typescript
// middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
  const { isLoggedIn } = useUser();
  if (!isLoggedIn.value) {
    return navigateTo(`/login?redirect=${encodeURIComponent(to.fullPath)}`);
  }
});
类型文件模式行为
命名中间件
middleware/auth.ts
通过 definePageMeta 手动启用
全局中间件
middleware/auth.global.ts
在每次导航时执行
内联中间件definePageMeta 中的函数页面专属逻辑
通过
definePageMeta({ middleware: "auth" })
或
definePageMeta({ middleware: ["auth", "admin"] })
绑定中间件。
重要提示: 使用
to
和
from
参数——不要在中间件中使用
useRoute()
(可能存在过期值)。
基于角色的权限验证、功能开关、访客拦截以及全局中间件模式请查看 examples/middleware.md。

Pattern 6: Layouts

模式6:布局

Layouts wrap pages with shared UI (navigation, footers). Default layout applies automatically.
vue
<!-- layouts/default.vue -->
<template>
  <div class="layout">
    <header>
      <nav><!-- Navigation --></nav>
    </header>
    <main><slot /></main>
    <footer><!-- Footer --></footer>
  </div>
</template>
Select layout per page:
definePageMeta({ layout: "admin" })
. Dynamic layout:
<NuxtLayout :name="computedLayout">
.
See examples/core.md for layout examples with auth-aware navigation.

布局通过共享UI(导航栏、页脚)包裹页面。默认布局会自动应用。
vue
<!-- layouts/default.vue -->
<template>
  <div class="layout">
    <header>
      <nav><!-- 导航栏 --></nav>
    </header>
    <main><slot /></main>
    <footer><!-- 页脚 --></footer>
  </div>
</template>
在页面中指定布局:
definePageMeta({ layout: "admin" })
。动态布局:
<NuxtLayout :name="computedLayout">
。
包含权限感知导航的布局示例请查看 examples/core.md。

Pattern 7: SEO with useHead and useSeoMeta

模式7:使用 useHead 和 useSeoMeta 优化SEO

vue
<script setup lang="ts">
const { data: post } = await useFetch(`/api/posts/${route.params.slug}`);

useSeoMeta({
  title: () => post.value?.title ?? "Blog Post",
  description: () => post.value?.excerpt ?? "",
  ogTitle: () => post.value?.title ?? "Blog Post",
  ogImage: () => post.value?.coverImage ?? "/default-og.png",
  twitterCard: "summary_large_image",
});
</script>
Why good: Reactive values with getter functions, type-safe property names, automatic Open Graph and Twitter cards, SSR-rendered
Global defaults in
nuxt.config.ts
via
app.head
. Page-level overrides via composables.

vue
<script setup lang="ts">
const { data: post } = await useFetch(`/api/posts/${route.params.slug}`);

useSeoMeta({
  title: () => post.value?.title ?? "博客文章",
  description: () => post.value?.excerpt ?? "",
  ogTitle: () => post.value?.title ?? "博客文章",
  ogImage: () => post.value?.coverImage ?? "/default-og.png",
  twitterCard: "summary_large_image",
});
</script>
优势: 通过 getter 函数支持响应式值,类型安全的属性名,自动生成 Open Graph 和 Twitter 卡片,支持SSR渲染
全局默认配置可在
nuxt.config.ts
中的
app.head
设置。页面级配置可通过组合式函数覆盖。

Pattern 8: Plugins

模式8:插件

Plugins run before Vue app creation. Use for registering global utilities or external libraries.
typescript
// plugins/api.client.ts  -- .client suffix = browser only
export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig();
  const api = $fetch.create({
    baseURL: config.public.apiBase,
    onRequest({ options }) {
      const token = useCookie("token");
      if (token.value) {
        options.headers = {
          ...options.headers,
          Authorization: `Bearer ${token.value}`,
        };
      }
    },
  });
  return { provide: { api } };
});
Access via
useNuxtApp().$api
. Suffixes:
.client.ts
(browser),
.server.ts
(server), no suffix (both).

插件在Vue应用创建前执行,用于注册全局工具或外部库。
typescript
// plugins/api.client.ts  -- .client 后缀 = 仅在浏览器中运行
export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig();
  const api = $fetch.create({
    baseURL: config.public.apiBase,
    onRequest({ options }) {
      const token = useCookie("token");
      if (token.value) {
        options.headers = {
          ...options.headers,
          Authorization: `Bearer ${token.value}`,
        };
      }
    },
  });
  return { provide: { api } };
});
通过
useNuxtApp().$api
访问插件提供的功能。后缀说明:
.client.ts
(仅浏览器)、
.server.ts
(仅服务端)、无后缀(两端都运行)。

Pattern 9: Error Handling

模式9:错误处理

typescript
// Server route errors
throw createError({
  statusCode: 404,
  statusMessage: "Not found",
  data: { id },
});

// Page-level: check useFetch error, throw createError
// Component-level: NuxtErrorBoundary with #error slot
// Global: error.vue at root level with clearError({ redirect: "/" })
createError
works in both server and client.
NuxtErrorBoundary
isolates component failures. Root
error.vue
catches unhandled errors.
See examples/core.md for error page and boundary examples.
</patterns>
Detailed Resources:
  • examples/core.md - Routing, layouts, error handling, auto-imports
  • examples/data-fetching.md - useFetch, useAsyncData, $fetch patterns
  • examples/server-routes.md - API routes, validation, server middleware
  • examples/middleware.md - Auth guards, role-based access, global middleware
  • examples/state-management.md - useState composables, persistence
  • reference.md - Decision frameworks, checklists, anti-patterns

<red_flags>
typescript
// 服务端路由错误
throw createError({
  statusCode: 404,
  statusMessage: "未找到",
  data: { id },
});

// 页面级:检查 useFetch 的错误,抛出 createError
// 组件级:使用 NuxtErrorBoundary 和 #error 插槽
// 全局:根目录下的 error.vue,使用 clearError({ redirect: "/" })
createError
在服务端和客户端均可使用。
NuxtErrorBoundary
可隔离组件错误。根目录下的
error.vue
可捕获未处理的错误。
错误页面和边界示例请查看 examples/core.md。
</patterns>
详细资源:
  • examples/core.md - 路由、布局、错误处理、自动导入
  • examples/data-fetching.md - useFetch、useAsyncData、$fetch 模式
  • examples/server-routes.md - API路由、验证、服务端中间件
  • examples/middleware.md - 权限拦截、基于角色的访问控制、全局中间件
  • examples/state-management.md - useState组合式函数、状态持久化
  • reference.md - 决策框架、检查清单、反模式

<red_flags>

RED FLAGS

注意事项

High Priority Issues:
  • Using
    $fetch
    directly in
    <script setup>
    for initial data -- causes double-fetching (server + client)
  • Non-serializable values in
    useState
    -- functions, classes, Symbols cause hydration errors
  • Missing
    key
    in
    useAsyncData
    for dynamic data -- leads to stale data and caching issues
  • useRoute()
    in middleware -- use
    to
    and
    from
    parameters instead; useRoute may have stale values
  • Secrets in client-side code -- use
    runtimeConfig
    private keys for server-only secrets
Medium Priority Issues:
  • Blocking data fetches without
    lazy: true
    -- slows navigation; use lazy for non-critical data
  • Not handling error state from useFetch -- always check and display
    error.value
  • Using
    onMounted
    for data that should be in useFetch -- misses SSR benefits
  • Forgetting
    await
    before
    useFetch
    in setup -- component renders before data is ready
Gotchas & Edge Cases:
  • useFetch
    URL is the cache key -- same URL = same cached data; use
    key
    option to differentiate
  • useState
    runs initializer only once per key -- subsequent calls return existing state
  • Middleware runs on both server and client -- use
    import.meta.server
    /
    import.meta.client
    to split
  • server/api/
    routes auto-prefix with
    /api
    --
    server/api/users.ts
    becomes
    /api/users
  • definePageMeta
    is a macro, not runtime -- values must be statically analyzable
  • NuxtLink
    with external URLs needs
    external
    prop or use
    <a>
    instead
  • Composables must be called synchronously in setup -- no
    await
    before first composable call
  • watch
    in
    useFetch
    requires reactive values -- plain variables won't trigger refetch
  • data
    from
    useFetch
    /
    useAsyncData
    is a
    shallowRef
    -- mutating nested properties won't trigger reactivity; replace the whole object or use
    deep: true
  • data
    and
    error
    default to
    undefined
    (not
    null
    ) -- adjust null checks accordingly
</red_flags>

<critical_reminders>
高优先级问题:
  • 在
    <script setup>
    中直接使用
    $fetch
    获取初始数据——导致重复请求(服务端+客户端)
  • useState
    中包含不可序列化的值——函数、类、Symbol会导致水合错误
  • 动态数据的
    useAsyncData
    缺少
    key
    ——导致数据过期和缓存问题
  • 在中间件中使用
    useRoute()
    ——请使用
    to
    和
    from
    参数;useRoute可能存在过期值
  • 客户端代码中包含敏感信息——请使用
    runtimeConfig
    的私有键存储服务端专属敏感信息
中优先级问题:
  • 未使用
    lazy: true
    的阻塞式数据请求——减慢导航速度;非关键数据请使用lazy模式
  • 未处理 useFetch 返回的错误状态——务必检查并展示
    error.value
  • 使用
    onMounted
    获取应通过useFetch获取的数据——失去SSR优势
  • 在setup中忘记在
    useFetch
    前添加
    await
    ——组件在数据准备好前就已渲染
陷阱与边缘情况:
  • useFetch
    的URL是缓存键——相同URL对应相同缓存数据;使用
    key
    选项区分不同请求
  • useState
    的初始化函数仅针对每个键执行一次——后续调用返回已有状态
  • 中间件在服务端和客户端都会运行——使用
    import.meta.server
    /
    import.meta.client
    区分环境
  • server/api/
    路由自动添加
    /api
    前缀——
    server/api/users.ts
    对应
    /api/users
  • definePageMeta
    是宏而非运行时函数——其值必须可被静态分析
  • 外部URL的
    NuxtLink
    需要添加
    external
    属性或直接使用
    <a>
    标签
  • 组合式函数必须在setup中同步调用——第一个组合式函数前不能使用
    await
  • useFetch
    中的
    watch
    需要响应式值——普通变量无法触发重新请求
  • useFetch
    /
    useAsyncData
    返回的
    data
    是
    shallowRef
    ——修改嵌套属性不会触发响应式;需替换整个对象或使用
    deep: true
  • data
    和
    error
    默认值为
    undefined
    (而非
    null
    )——请相应调整空值检查逻辑
</red_flags>

<critical_reminders>

CRITICAL REMINDERS

重要提醒

All code must follow project conventions in CLAUDE.md
(You MUST use
useFetch
or
useAsyncData
for data fetching in components -- NEVER raw
$fetch
in setup which causes double-fetching)
(You MUST use
server/api/
for API routes -- handlers export default with
defineEventHandler()
)
(You MUST use
definePageMeta
to attach middleware and configure page behavior -- it is a macro, values must be statically analyzable)
(You MUST use
useHead
or
useSeoMeta
for SEO metadata -- never manual
<head>
tags)
(You MUST ensure
useState
values are JSON-serializable for SSR hydration -- no functions, classes, or Symbols)
Failure to follow these rules will cause SSR hydration mismatches, double-fetching, and broken page metadata.
</critical_reminders>
所有代码必须遵循 CLAUDE.md 中的项目约定
(在组件中进行数据获取时,必须使用
useFetch
或
useAsyncData
——绝对不要在 setup 中直接使用
$fetch
,这会导致重复请求)
(必须使用
server/api/
来创建 API 路由——处理器需通过
defineEventHandler()
导出默认函数)
(必须使用
definePageMeta
来绑定中间件并配置页面行为——这是一个宏,其值必须可被静态分析)
(必须使用
useHead
或
useSeoMeta
来设置 SEO 元数据——绝不要手动编写
<head>
标签)
(必须确保
useState
的值可被 JSON 序列化,以支持 SSR 水合——不能包含函数、类或 Symbol)
不遵守这些规则会导致SSR水合不匹配、重复请求以及页面元数据失效。
</critical_reminders>