路由类

definePageMeta

定义页面元信息，只能在页面组件中使用（自动编译为路由配置）。

function definePageMeta(meta: {
  layout?: string | { name: string; props?: Record<string, any> }
  middleware?: string | string[]
  key?: string | ((route: RouteLocationNormalized) => string)
  pageTransition?: TransitionProps
  layoutTransition?: TransitionProps
  keepalive?: boolean | KeepAliveProps
  validate?: (route: RouteLocationNormalized) => boolean | Promise<boolean>
  redirect?: string
  name?: string
  path?: string
  props?: boolean | Function
  // 可添加自定义属性
  [key: string]: any
}): void

常用配置

definePageMeta({
  layout: 'admin',                    // 布局
  middleware: 'auth',                  // 中间件
  key: route => route.fullPath,       // 页面 key
  pageTransition: { name: 'fade' },   // 页面过渡
  layoutTransition: { name: 'fade' }, // 布局过渡
  keepalive: true,                     // 缓存页面
  validate: (route) => true,          // 路由验证

  // v4.4+: 布局 Props
  layout: { name: 'panel', props: { sidebar: true } },

  // 自定义元信息（可在中间件中读取）
  requiresAuth: true,
  title: '用户管理',
})

路由验证

// 验证路由参数，返回 false 显示 404
definePageMeta({
  validate: (route) => {
    return /^\d+$/.test(route.params.id as string)
  },
})

多个中间件

definePageMeta({
  middleware: ['auth', 'admin-only'],
})

读取自定义元信息

// 在中间件中读取
export default defineNuxtRouteMiddleware((to) => {
  if (to.meta.requiresAuth && !isAuthenticated()) {
    return navigateTo('/login')
  }
})

INFO

️ definePageMeta 必须在 <script setup> 或 setup() 的顶层调用 不能在条件语句中使用

---

defineRouteRules

在页面中定义路由规则（ISR、预渲染、CORS 等）。

function defineRouteRules(rules: {
  swr?: number | boolean           // 缓存时间(秒)
  isr?: number | boolean           // ISR 缓存
  prerender?: boolean              // 是否预渲染
  cors?: boolean                   // CORS
  headers?: Record<string, string>  // 响应头
}): void

常用配置

// ISR 缓存 1 小时
defineRouteRules({
  swr: 3600,
})

// 预渲染
defineRouteRules({
  prerender: true,
})

// 自定义响应头
defineRouteRules({
  headers: {
    'Cache-Control': 'max-age=3600',
    'X-Custom': 'value',
  },
})

TIP

也可以在 nuxt.config.ts 中通过 routeRules 全局配置 defineRouteRules 适合页面级别的配置

---

preloadRouteComponents

预加载路由组件（提前下载 JS，但不导航）。

function preloadRouteComponents(
  route: string  // 目标路由路径
): Promise<void>

// 预加载目标路由的组件
await preloadRouteComponents('/dashboard')

// 鼠标悬停时预加载
function onHover() {
  preloadRouteComponents('/dashboard')
}

// 在导航守卫中预加载
export default defineNuxtRouteMiddleware((to) => {
  preloadRouteComponents('/dashboard/charts')
})

TIP

预加载会提前下载 JS chunk 但不会执行组件代码，适合用户可能访问的页面

---

prerenderRoutes

声明需要预渲染的路由（在构建时生成静态 HTML）。

function prerenderRoutes(
  routes: string | string[]  // 路由路径
): void

// 单个路由
prerenderRoutes('/blog/latest')

// 多个路由
prerenderRoutes(['/blog/1', '/blog/2', '/blog/3'])

// 动态生成路由列表
const { data: posts } = await useFetch('/api/posts')
prerenderRoutes(posts.value.map(p => `/blog/${p.slug}`))

INFO

️ prerenderRoutes 仅在 SSG 模式（nuxt generate）构建时有效 开发模式和 SSR 模式下无效果