导航类

navigateTo

SSR 安全的编程式导航函数，支持内部路由和外部链接。

function navigateTo(
  to: string | RouteLocationRaw,  // 目标路由
  options?: {
    external?: boolean             // 是否外部链接
    replace?: boolean              // 替换当前历史记录
    open?: { target: string }      // 新窗口打开
    redirectCode?: number         // 服务端重定向状态码
  }
): Promise<void | false | RouteLocationRaw>

基本用法

// 内部路由
await navigateTo('/about')

// 带查询参数
await navigateTo({ path: '/search', query: { q: 'nuxt' } })

// 外部链接
await navigateTo('https://nuxt.com', { external: true })

// 替换历史记录（不产生新记录）
await navigateTo('/login', { replace: true })

// 新窗口打开
await navigateTo('/report', { open: { target: '_blank' } })

在中间件中使用

在路由中间件中使用时，必须 return 导航结果：

// ✅ 正确
export default defineNuxtRouteMiddleware((to) => {
  if (!isAuthenticated()) {
    return navigateTo('/login')
  }
})

// ❌ 错误 - 不会阻止导航
export default defineNuxtRouteMiddleware((to) => {
  if (!isAuthenticated()) {
    navigateTo('/login')  // 没有 return！
  }
})

服务端重定向

// server/api/redirect.ts
export default defineEventHandler((event) => {
  return navigateTo('/new-path', { redirectCode: 301 })
})

// 301 永久重定向 / 302 临时重定向
return navigateTo('/new-url', { redirectCode: 302 })

INFO

️ 在中间件中如果不 return navigateTo() 导航不会被阻止，会继续到目标页面

---

abortNavigation

在中间件中阻止当前导航，用户留在当前页面。

function abortNavigation(
  error?: string | Error | Partial<NuxtError>  // 可选的错误信息
): false | RouteLocationRaw

基本用法

// 静默阻止导航
export default defineNuxtRouteMiddleware((to) => {
  if (to.path === '/disabled') {
    return abortNavigation()
  }
})

// 带错误信息阻止
export default defineNuxtRouteMiddleware((to) => {
  if (!hasPermission(to)) {
    return abortNavigation(createError({
      statusCode: 403,
      statusMessage: 'Forbidden',
      message: '无权访问此页面',
    }))
  }
})

abortNavigation vs navigateTo

函数	行为	用户看到
abortNavigation()	阻止导航，留在当前页	无变化
abortNavigation(error)	阻止导航，显示错误	错误页面
navigateTo('/login')	导航到新页面	跳转到登录页

---

addRouteMiddleware

动态添加路由中间件（非文件系统方式）。

function addRouteMiddleware(
  name: string,                        // 中间件名称
  middleware: RouteMiddlewareFunction, // 中间件函数
  options?: { global: boolean }        // 是否全局中间件
): void

基本用法

// 添加命名中间件（仅在页面中引用时执行）
addRouteMiddleware('auth', () => {
  if (!isAuthenticated()) return navigateTo('/login')
})

// 添加全局中间件（每次导航都执行）
addRouteMiddleware('track', () => {
  trackPageView()
}, { global: true })

在插件中注册中间件

// plugins/setup-middleware.ts
export default defineNuxtPlugin(() => {
  addRouteMiddleware('auth', (to) => {
    const token = useCookie('auth-token')
    if (!token.value) return navigateTo('/login')
  }, { global: true })
})

TIP

文件系统中间件（app/middleware/ 目录）是更常用的方式 addRouteMiddleware 适合需要动态注册的场景