路由导航类

函数	用途	SSR 安全	返回值
useRouter	Vue Router 实例	❌ 仅客户端	Router
useRoute	当前路由信息	✅	Route
navigateTo	编程式导航	✅	Promise<void>
abortNavigation	阻止导航	✅	false

useRouter

获取 Vue Router 实例，用于编程式导航。

const router = useRouter()

// 导航
router.push('/about')       // 前进
router.replace('/about')    // 替换（不留历史记录）
router.back()                // 后退
router.forward()             // 前进
router.go(1)                // 前进 1 步

// 钩子
router.beforeEach((to, from) => { /* ... */ })
router.afterEach((to, from) => { /* ... */ })

INFO

️ useRouter 仅客户端可用 服务端使用 navigateTo

TIP

在路由中间件中也推荐用 navigateTo 而非 router.push

useRoute

获取当前路由信息，响应式。

const route = useRoute()

route.path           // '/user/1'
route.fullPath       // '/user/1?tab=profile#section'
route.params         // { id: '1' }
route.query          // { tab: 'profile' }
route.hash           // '#section'
route.name           // 'user-id'
route.meta           // 路由元信息
route.matched        // 匹配的路由记录
route.redirectedFrom // 重定向前路由

监听路由变化

watch(() => route.params.id, (newId) => {
// 路由参数变化时执行
})

INFO

️ route.params 和 route.query 的值都是 string 类型 需要手动转换

const id = Number(route.params.id)  // '123' → 123
const page = Number(route.query.page) || 1

navigateTo

SSR 安全的编程式导航，在服务端和客户端都可用。

// 基本导航
await navigateTo('/about')

// 外部链接（必须指定 external）
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')  // 必须返回
  }
})

navigateTo vs router.push

• navigateTo：SSR 安全，可以在中间件和服务端使用
• router.push：仅客户端，功能更丰富

推荐统一使用 navigateTo

在所有场景下都能正确工作。

abortNavigation

在路由中间件中阻止导航，不跳转。

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

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

abortNavigation vs navigateTo

• abortNavigation：阻止导航，留在当前页
• navigateTo：跳转到其他页面

TIP

在中间件中 返回 abortNavigation() 阻止导航，返回 navigateTo() 重定向