web-meta-framework-nuxt
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseNuxt Framework Patterns
Nuxt 框架模式
Quick Guide: Usefor API calls in components (SSR-safe),useFetchfor custom data sources or parallel fetches. Create server routes inuseAsyncData. Auto-imports handle composables and components automatically. Useserver/api/for SSR-friendly shared state. Data is auseStateby default -- useshallowRefif you need deep reactivity.deep: true
<critical_requirements>
快速指南: 在组件中使用进行 API 调用(支持SSR),useFetch用于自定义数据源或并行请求。在useAsyncData目录下创建服务端路由。自动导入功能会自动处理组合式函数和组件。使用server/api/实现支持SSR的共享状态。默认情况下数据是useState——如果需要深度响应式,请使用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,, named constants)import type
(You MUST use or for data fetching in components -- NEVER raw in setup which causes double-fetching)
useFetchuseAsyncData$fetch(You MUST use for API routes -- handlers export default with )
server/api/defineEventHandler()(You MUST use to attach middleware and configure page behavior -- it is a macro, values must be statically analyzable)
definePageMeta(You MUST use or for SEO metadata -- never manual tags)
useHeaduseSeoMeta<head>(You MUST ensure values are JSON-serializable for SSR hydration -- no functions, classes, or Symbols)
useState</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
(在组件中进行数据获取时,必须使用 或 ——绝对不要在 setup 中直接使用 ,这会导致重复请求)
useFetchuseAsyncData$fetch(必须使用 来创建 API 路由——处理器需通过 导出默认函数)
server/api/defineEventHandler()(必须使用 来绑定中间件并配置页面行为——这是一个宏,其值必须可被静态分析)
definePageMeta(必须使用 或 来设置 SEO 元数据——绝不要手动编写 标签)
useHeaduseSeoMeta<head>(必须确保 的值可被 JSON 序列化,以支持 SSR 水合——不能包含函数、类或 Symbol)
useState</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:
- Universal rendering by default -- Pages render on server first, then hydrate on client
- Auto-imports everywhere -- Composables, components, and utilities are automatically available
- File-based conventions -- Directories define behavior (pages/, server/, layouts/, middleware/)
- SSR-safe data fetching -- Composables prevent double-fetching between server and client
- Zero-config TypeScript -- Full type safety with automatic type generation
- Shallow reactivity for performance -- from
data/useFetchis auseAsyncDataby defaultshallowRef
<patterns>
Nuxt 是一款 Vue 3 元框架,提供基于文件的路由、自动代码分割、服务端渲染以及强大的数据获取系统。它构建于 Nitro 服务引擎之上,支持将 API 路由与前端代码放在同一项目中,实现全栈开发。
核心原则:
- 默认支持通用渲染——页面先在服务端渲染,然后在客户端进行水合
- 全局自动导入——组合式函数、组件和工具函数可直接使用
- 基于文件的约定——目录结构定义功能(pages/、server/、layouts/、middleware/)
- 支持SSR的数据获取——组合式函数避免服务端与客户端之间的重复请求
- 零配置 TypeScript——通过自动类型生成实现完整的类型安全
- 浅响应式提升性能——/
useFetch返回的useAsyncData默认是datashallowRef
<patterns>
Core Patterns
核心模式
Pattern 1: File-Based Routing
模式1:基于文件的路由
File names in become URL paths. Dynamic segments use bracket syntax.
pages/| File | URL | Description |
|---|---|---|
| | Home page |
| | Static route |
| | Dynamic parameter |
| | Catch-all route |
| | 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 路径 | 描述 |
|---|---|---|
| | 首页 |
| | 静态路由 |
| | 动态参数路由 |
| | 通配符路由 |
| | 可选参数路由 |
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)
useFetchuseAsyncData$fetchshallowRefdeep: truetypescript
// 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 when combining multiple fetches or using non-HTTP sources:
useAsyncDatatypescript
const { data } = await useAsyncData("dashboard", async () => {
const [users, stats] = await Promise.all([
$fetch("/api/users"),
$fetch("/api/stats"),
]);
return { users, stats };
});Critical: in (outside useFetch/useAsyncData) runs on both server and client, causing double-fetching. Always wrap in a composable.
$fetch<script setup>See examples/data-fetching.md for typed responses, transforms, lazy loading, and server-only fetch patterns.
useFetchuseAsyncData$fetchdatashallowRefdeep: truetypescript
// 简单请求——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数据源时,使用 :
useAsyncDatatypescript
const { data } = await useAsyncData("dashboard", async () => {
const [users, stats] = await Promise.all([
$fetch("/api/users"),
$fetch("/api/stats"),
]);
return { users, stats };
});重要提示: 在 中直接使用 (未包裹在useFetch/useAsyncData中)会同时在服务端和客户端执行,导致重复请求。务必将其包裹在组合式函数中。
<script setup>$fetch类型化响应、数据转换、懒加载以及服务端专属请求模式请查看 examples/data-fetching.md。
Pattern 3: Server Routes
模式3:服务端路由
Server routes live in (prefixed with ) or (no prefix). File suffix restricts HTTP method.
server/api//apiserver/routes/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 });
});| Pattern | File | URL |
|---|---|---|
| GET | | |
| POST | | |
| Dynamic | | |
| Catch-all | | |
| No prefix | | |
See examples/server-routes.md for validation, error handling, server middleware, and CRUD patterns.
服务端路由位于 (自动添加 前缀)或 (无前缀)。文件后缀限制HTTP请求方法。
server/api//apiserver/routes/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 请求 | | |
| POST 请求 | | |
| 动态路由 | | |
| 通配符路由 | | |
| 无前缀路由 | | |
验证、错误处理、服务端中间件以及CRUD模式请查看 examples/server-routes.md。
Pattern 4: useState for Shared State
模式4:使用 useState 管理共享状态
useStatetypescript
// 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.
useStatetypescript
// 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)}`);
}
});| Type | File Pattern | Behavior |
|---|---|---|
| Named | | Opt-in via definePageMeta |
| Global | | Runs on every navigation |
| Inline | Function in definePageMeta | Page-specific logic |
Attach via or .
definePageMeta({ middleware: "auth" })definePageMeta({ middleware: ["auth", "admin"] })Critical: Use and parameters -- never in middleware (may have stale values).
tofromuseRoute()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)}`);
}
});| 类型 | 文件模式 | 行为 |
|---|---|---|
| 命名中间件 | | 通过 definePageMeta 手动启用 |
| 全局中间件 | | 在每次导航时执行 |
| 内联中间件 | definePageMeta 中的函数 | 页面专属逻辑 |
通过 或 绑定中间件。
definePageMeta({ middleware: "auth" })definePageMeta({ middleware: ["auth", "admin"] })重要提示: 使用 和 参数——不要在中间件中使用 (可能存在过期值)。
tofromuseRoute()基于角色的权限验证、功能开关、访客拦截以及全局中间件模式请查看 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: . Dynamic layout: .
definePageMeta({ layout: "admin" })<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 via . Page-level overrides via composables.
nuxt.config.tsapp.headvue
<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.tsapp.headPattern 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 . Suffixes: (browser), (server), no suffix (both).
useNuxtApp().$api.client.ts.server.ts插件在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.tsPattern 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: "/" })createErrorNuxtErrorBoundaryerror.vueSee 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: "/" })createErrorNuxtErrorBoundaryerror.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 directly in
$fetchfor initial data -- causes double-fetching (server + client)<script setup> - Non-serializable values in -- functions, classes, Symbols cause hydration errors
useState - Missing in
keyfor dynamic data -- leads to stale data and caching issuesuseAsyncData - in middleware -- use
useRoute()andtoparameters instead; useRoute may have stale valuesfrom - Secrets in client-side code -- use private keys for server-only secrets
runtimeConfig
Medium Priority Issues:
- Blocking data fetches without -- slows navigation; use lazy for non-critical data
lazy: true - Not handling error state from useFetch -- always check and display
error.value - Using for data that should be in useFetch -- misses SSR benefits
onMounted - Forgetting before
awaitin setup -- component renders before data is readyuseFetch
Gotchas & Edge Cases:
- URL is the cache key -- same URL = same cached data; use
useFetchoption to differentiatekey - runs initializer only once per key -- subsequent calls return existing state
useState - Middleware runs on both server and client -- use /
import.meta.serverto splitimport.meta.client - routes auto-prefix with
server/api/--/apibecomesserver/api/users.ts/api/users - is a macro, not runtime -- values must be statically analyzable
definePageMeta - with external URLs needs
NuxtLinkprop or useexternalinstead<a> - Composables must be called synchronously in setup -- no before first composable call
await - in
watchrequires reactive values -- plain variables won't trigger refetchuseFetch - from
data/useFetchis auseAsyncData-- mutating nested properties won't trigger reactivity; replace the whole object or useshallowRefdeep: true - and
datadefault toerror(notundefined) -- adjust null checks accordinglynull
</red_flags>
<critical_reminders>
高优先级问题:
- 在 中直接使用
<script setup>获取初始数据——导致重复请求(服务端+客户端)$fetch - 中包含不可序列化的值——函数、类、Symbol会导致水合错误
useState - 动态数据的 缺少
useAsyncData——导致数据过期和缓存问题key - 在中间件中使用 ——请使用
useRoute()和to参数;useRoute可能存在过期值from - 客户端代码中包含敏感信息——请使用 的私有键存储服务端专属敏感信息
runtimeConfig
中优先级问题:
- 未使用 的阻塞式数据请求——减慢导航速度;非关键数据请使用lazy模式
lazy: true - 未处理 useFetch 返回的错误状态——务必检查并展示
error.value - 使用 获取应通过useFetch获取的数据——失去SSR优势
onMounted - 在setup中忘记在 前添加
useFetch——组件在数据准备好前就已渲染await
陷阱与边缘情况:
- 的URL是缓存键——相同URL对应相同缓存数据;使用
useFetch选项区分不同请求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——修改嵌套属性不会触发响应式;需替换整个对象或使用shallowRefdeep: true - 和
data默认值为error(而非undefined)——请相应调整空值检查逻辑null
</red_flags>
<critical_reminders>
CRITICAL REMINDERS
重要提醒
All code must follow project conventions in CLAUDE.md
(You MUST use or for data fetching in components -- NEVER raw in setup which causes double-fetching)
useFetchuseAsyncData$fetch(You MUST use for API routes -- handlers export default with )
server/api/defineEventHandler()(You MUST use to attach middleware and configure page behavior -- it is a macro, values must be statically analyzable)
definePageMeta(You MUST use or for SEO metadata -- never manual tags)
useHeaduseSeoMeta<head>(You MUST ensure values are JSON-serializable for SSR hydration -- no functions, classes, or Symbols)
useStateFailure to follow these rules will cause SSR hydration mismatches, double-fetching, and broken page metadata.
</critical_reminders>
所有代码必须遵循 CLAUDE.md 中的项目约定
(在组件中进行数据获取时,必须使用 或 ——绝对不要在 setup 中直接使用 ,这会导致重复请求)
useFetchuseAsyncData$fetch(必须使用 来创建 API 路由——处理器需通过 导出默认函数)
server/api/defineEventHandler()(必须使用 来绑定中间件并配置页面行为——这是一个宏,其值必须可被静态分析)
definePageMeta(必须使用 或 来设置 SEO 元数据——绝不要手动编写 标签)
useHeaduseSeoMeta<head>(必须确保 的值可被 JSON 序列化,以支持 SSR 水合——不能包含函数、类或 Symbol)
useState不遵守这些规则会导致SSR水合不匹配、重复请求以及页面元数据失效。
</critical_reminders>