Vue 3 Composition API 路由控制：useRouter 与 useRoute 实战指南

1. 从 Options API 到 Composition API：路由控制的新思路

如果你是从 Vue 2 升级到 Vue 3 的开发者，或者刚开始接触 Vue 3，那么你肯定对this.$router和this.$route这两个老朋友不陌生。在 Options API 时代，我们几乎在每个组件里都会用到它们，一个负责“指挥交通”（跳转页面），一个负责“查看路况”（获取当前页面信息）。但到了 Composition API 的时代，一切都变得有点不一样了。我们不再依赖this，代码的组织方式也从“选项式”变成了“函数式”。这时候，useRouter和useRoute就闪亮登场了。

我刚开始用 Vue 3 写项目的时候，也习惯性地在setup里找this，结果当然是找不到。后来才明白，Composition API 的核心思想就是把逻辑拆分成一个个可复用的函数，而useRouter和useRoute就是vue-router专门为这种模式提供的两个“入口函数”。你可以把它们理解成两个“钩子”，专门用来把路由相关的功能“钩”进你的组件逻辑里。

简单来说，useRouter就是原来this.$router的替代品，它给你一个路由器实例，让你能指挥页面跳转、前进后退。而useRoute就是this.$route的替代品，它给你一个响应式的对象，里面装着当前页面所有的路由信息，比如路径、参数、查询字符串等等。听起来好像只是换了个名字？实战用起来你会发现，配合 Composition API 的写法，代码的灵活性和可维护性提升了一大截。这篇文章，我就结合我踩过的坑和积累的经验，带你彻底玩转这两个钩子，让路由控制变得像搭积木一样简单清晰。

2. 深入 useRouter：你的应用导航指挥官

useRouter是你在组件内部发起导航的“总开关”。调用它，你会拿到整个应用的路由器实例，接下来所有的跳转操作都由它来执行。

2.1 基础导航：跳转页面的几种姿势

最常用的导航方法无疑是router.push。它和我们之前在浏览器地址栏输入一个新地址然后回车效果类似，会在历史记录里添加一条新记录。这意味着用户点击浏览器的后退按钮，可以回到之前的页面。

import { useRouter } from 'vue-router' export default { setup() { const router = useRouter() // 方法一：字符串路径（最简单直接） const goHome = () => { router.push('/home') } // 方法二：描述地址的对象（功能最全） const goToUser = (userId) => { router.push({ path: `/user/${userId}` }) } // 方法三：命名路由（推荐！维护性最好） const goToProfile = () => { router.push({ name: 'userProfile', // 对应路由配置里的 name 属性 params: { id: 123 } // 传递动态参数 }) } // 方法四：带查询参数 const search = (keyword) => { router.push({ path: '/search', query: { q: keyword, page: 1 } // 生成 /search?q=vue&page=1 }) } return { goHome, goToUser, goToProfile, search } } }

这里有个我踩过的“坑”需要特别注意：params和query的区别。当你使用path属性时，params是不生效的！params必须和name属性配对使用。上面例子中的goToProfile方法，如果路由配置里定义了name: 'userProfile', path: '/user/:id'，那么跳转后地址栏会正确显示为/user/123。但如果你错误地写成router.push({ path: '/user/123', params: { id: 123 } })，这个params会被忽略。而query（查询参数）则无论用path还是name都可以正常工作，它会以?key=value的形式附加在URL后面。

2.2 进阶操作：替换、前进与守卫

除了push，useRouter返回的实例还有其他几个非常实用的方法。

router.replace和push很像，但关键区别在于它不会往历史记录栈里添加新记录，而是替换掉当前的记录。这个特性在哪些场景下有用呢？比如一个登录页面，登录成功后跳转到首页，你通常不希望用户还能通过后退按钮退回到登录页。这时候用replace就非常合适。

const loginSuccess = () => { // 登录后跳转首页，并替换当前历史记录 router.replace('/dashboard') }

router.go、router.back、router.forward这三个方法则是用来在历史记录里穿梭的，相当于模拟用户点击浏览器的前进后退按钮。这在一些需要自定义导航逻辑的组件里很好用，比如一个自定义的图片查看器，左右箭头可以切换图片，同时也要同步更新浏览器历史。

const goForward = () => router.forward() // 前进一步 const goBack = () => router.back() // 后退一步 const goSteps = (n) => router.go(n) // 前进或后退 n 步，n为负数表示后退

更强大的是，router实例还提供了导航守卫的编程式接口。你可以在一次导航中动态地添加守卫逻辑。比如，在提交一个表单并跳转前，你可能需要先进行一些异步验证。

const submitForm = async () => { // 调用一个异步验证函数 const isValid = await validateForm() if (isValid) { // 执行导航，并可以添加成功或失败的回调 router.push('/success').then(() => { console.log('导航成功！') }).catch((err) => { // 导航被中断（例如在另一个守卫中被取消了） if (err.name === 'NavigationDuplicated') { console.warn('重复导航到相同位置') } else { console.error('导航失败：', err) } }) } }

这里特别提一下NavigationDuplicated这个错误。这是vue-router4 引入的一个变化。在 Vue 2 的vue-router里，你连续点击同一个链接或调用相同的push操作，控制台会有一个警告。而在 Vue 3 的vue-router4 中，这会直接抛出一个可捕获的错误。如果你不想处理这个错误，可以在创建路由实例时配置{ strict: false }，或者像上面一样在catch里忽略它。

3. 玩转 useRoute：实时掌握路由动态信息

如果说useRouter是“指挥官”，那么useRoute就是你的“情报员”。它返回一个响应式的对象，里面包含了当前激活路由的所有信息。这个对象是响应式的，意味着当路由发生变化时（比如用户手动修改了URL的查询参数），任何依赖它的计算属性或侦听器都会自动更新。

3.1 核心属性详解

我们来看看route对象里最常用的几个属性，并通过例子理解它们。

import { useRoute } from 'vue-router' import { computed, watch } from 'vue' export default { setup() { const route = useRoute() // 1. path - 当前路由的路径部分 console.log('当前路径：', route.path) // 例如：'/user/123/profile' // 2. params - 动态路由参数（非常重要！） // 假设路由配置为：{ path: '/user/:id/profile/:tab?' } // 访问 /user/123/profile/settings const userId = route.params.id // '123' const activeTab = route.params.tab // 'settings' // 注意：所有 params 值都是字符串。如果路由定义是 /user/:id，那么 id 就是字符串类型。 // 3. query - 查询参数（URL中 ? 后面的部分） // 访问 /search?q=vue&sort=desc const searchKeyword = route.query.q // 'vue' const sortOrder = route.query.sort // 'desc' // query 参数也是字符串。对于多值参数 ?tag=vue&tag=js，route.query.tag 会是一个数组 ['vue', 'js'] // 4. hash - URL 的 hash 部分（带 #） // 访问 /about#team const hashValue = route.hash // '#team' // 5. fullPath - 完整的 URL 路径（包含查询参数和 hash） // 访问 /search?q=vue#results const full = route.fullPath // '/search?q=vue#results' // 6. name - 路由配置中定义的名称（如果当前路由有命名的话） const routeName = route.name return { userId, activeTab, searchKeyword } } }

在实际项目中，params和query是用得最多的。我个人的经验是：用params来标识资源的唯一性（比如用户ID、文章ID），用query来传递过滤、排序、分页等可选状态（比如搜索关键词、页码、排序方式）。这样设计出来的URL既清晰又符合 RESTful 风格。

3.2 响应式监听与计算属性

由于route对象是响应式的，我们可以非常方便地使用 Vue 的响应式系统来监听路由变化或创建依赖路由的计算属性。这是 Composition API 带来的巨大优势。

场景一：根据查询参数动态过滤列表。假设我们有一个商品列表页，URL 中的category和sort参数决定了显示哪些商品以及排序方式。

import { useRoute, onBeforeRouteUpdate } from 'vue-router' import { ref, computed, watchEffect } from 'vue' import { fetchProducts } from './api' export default { setup() { const route = useRoute() const productList = ref([]) const loading = ref(false) // 方法A：使用 watchEffect 自动追踪依赖 watchEffect(async () => { loading.value = true try { // 当 route.query.category 或 route.query.sort 变化时，这个函数会自动重新执行 productList.value = await fetchProducts({ category: route.query.category || 'all', sort: route.query.sort || 'default' }) } catch (error) { console.error('获取商品失败', error) } finally { loading.value = false } }) // 方法B：使用计算属性（适用于同步衍生数据） const isSearching = computed(() => { return !!route.query.q // 如果有搜索关键词 q，则认为正在搜索 }) // 方法C：使用 onBeforeRouteUpdate 守卫（更精细的控制） onBeforeRouteUpdate(async (to, from) => { // 只有当 category 参数变化时才重新获取数据 if (to.query.category !== from.query.category) { loading.value = true productList.value = await fetchProducts({ category: to.query.category }) loading.value = false } }) return { productList, loading, isSearching } } }

watchEffect在这里非常强大，它自动收集函数体内用到的响应式数据（这里是route.query的两个属性）作为依赖，一旦依赖变化就重新执行副作用函数（重新获取商品）。这比在 Options API 里用watch: { '$route.query' }要简洁直观得多。

场景二：在组件内守卫中访问路由信息。onBeforeRouteUpdate和onBeforeRouteLeave是vue-router提供的两个组合式 API 导航守卫。它们特别适合在组件内部处理一些离开或更新前的逻辑，比如表单未保存的提示。

import { onBeforeRouteLeave } from 'vue-router' import { ref } from 'vue' export default { setup() { const formData = ref({}) const isDirty = ref(false) // 监听表单变化 // ... 这里省略表单绑定的逻辑 onBeforeRouteLeave((to, from) => { if (isDirty.value) { const answer = window.confirm('你有未保存的更改，确定要离开吗？') if (!answer) { return false // 取消导航 } } }) return { formData } } }

4. 实战进阶：组合 useRouter 与 useRoute 的典型场景

单独使用useRouter或useRoute已经能解决大部分问题，但将它们组合起来，才能发挥 Composition API 真正的威力。下面我分享几个在真实项目中非常实用的模式。

4.1 构建一个带分页和过滤的列表页

这是一个非常经典的后台管理或电商场景。我们需要根据URL参数来展示列表，并且任何分页、筛选操作都要同步更新到URL，以便分享或刷新页面后状态不丢失。

<template> <div> <h1>用户列表</h1> <!-- 搜索框 --> <input v-model="searchKeyword" @input="handleSearch" placeholder="搜索用户..."> <!-- 过滤器 --> <select v-model="selectedRole" @change="handleFilterChange"> <option value="">所有角色</option> <option value="admin">管理员</option> <option value="user">普通用户</option> </select> <!-- 用户列表 --> <ul> <li v-for="user in users" :key="user.id">{{ user.name }}</li> </ul> <!-- 分页 --> <div> <button @click="goToPage(currentPage - 1)" :disabled="currentPage === 1">上一页</button> <span>第 {{ currentPage }} 页</span> <button @click="goToPage(currentPage + 1)">下一页</button> </div> </div> </template> <script> import { useRouter, useRoute } from 'vue-router' import { ref, computed, watchEffect } from 'vue' import { fetchUsers } from './api' export default { setup() { const router = useRouter() const route = useRoute() // 从 URL 中初始化状态 const searchKeyword = ref(route.query.q || '') const selectedRole = ref(route.query.role || '') const currentPage = ref(parseInt(route.query.page) || 1) const users = ref([]) const loading = ref(false) // 监听所有路由参数变化，获取数据 watchEffect(async () => { loading.value = true try { users.value = await fetchUsers({ q: route.query.q, role: route.query.role, page: route.query.page, pageSize: 10 }) } finally { loading.value = false } }) // 更新 URL 的通用函数 const updateQuery = (newQuery) => { router.push({ // 保持当前路径和命名 name: route.name || undefined, // 合并旧的查询参数和新的参数，用新值覆盖旧值 query: { ...route.query, ...newQuery } }) } // 搜索处理（防抖可以在外部实现） const handleSearch = () => { updateQuery({ q: searchKeyword.value, page: 1 }) // 搜索时重置到第一页 } // 过滤处理 const handleFilterChange = () => { updateQuery({ role: selectedRole.value, page: 1 }) } // 分页处理 const goToPage = (page) => { if (page < 1) return updateQuery({ page }) } // 同步 URL 变化到本地 ref（当用户手动修改URL或点击浏览器前进后退时） watchEffect(() => { searchKeyword.value = route.query.q || '' selectedRole.value = route.query.role || '' currentPage.value = parseInt(route.query.page) || 1 }) return { searchKeyword, selectedRole, currentPage, users, loading, handleSearch, handleFilterChange, goToPage } } } </script>

这个例子展示了完整的闭环：UI操作（输入、选择、点击）通过useRouter更新URL，URL的变化通过useRoute被watchEffect捕获并触发数据重新获取，新的数据再渲染到UI。所有状态都保存在URL里，用户体验非常好。

4.2 实现一个权限验证与路由拦截的 Composable

在大型应用中，权限控制是必不可少的。我们可以利用useRouter和useRoute创建一个可复用的权限验证逻辑。

// composables/useAuth.js import { useRouter, useRoute } from 'vue-router' import { computed } from 'vue' import { checkUserPermission } from './permission' // 假设的权限检查函数 export function useAuth() { const router = useRouter() const route = useRoute() // 假设我们从全局状态（如 Pinia）获取用户角色 // 这里为了示例，简单模拟 const userRole = ref('guest') // 检查当前路由是否需要特定权限 const requiredPermission = computed(() => { // 可以从路由元信息 meta 中获取权限要求 return route.meta?.requiresAuth || route.meta?.permission }) // 检查当前用户是否有权限访问当前路由 const hasPermission = computed(() => { if (!requiredPermission.value) { return true // 路由不需要权限 } return checkUserPermission(userRole.value, requiredPermission.value) }) // 一个导航守卫函数，可以在路由配置的全局守卫或组件内调用 const authGuard = (to, from) => { const permissionRequired = to.meta?.requiresAuth if (permissionRequired && !hasPermission.value) { // 如果没有权限，重定向到登录页或无权限页面 // 可以携带原目标路径，以便登录后回跳 return { path: '/login', query: { redirect: to.fullPath } } } } // 编程式导航到受保护路由前的检查 const navigateToProtected = (location) => { // 这里可以模拟检查目标路由的权限 const targetRoute = router.resolve(location) // 解析路由位置 if (targetRoute.meta?.requiresAuth && !hasPermission.value) { router.push({ path: '/login', query: { redirect: targetRoute.fullPath } }) } else { router.push(location) } } return { userRole, hasPermission, authGuard, navigateToProtected } }

然后在你的路由配置中，可以这样定义元信息：

// router/index.js const routes = [ { path: '/dashboard', name: 'Dashboard', component: () => import('@/views/Dashboard.vue'), meta: { requiresAuth: true, permission: 'view_dashboard' } }, { path: '/admin', name: 'Admin', component: () => import('@/views/Admin.vue'), meta: { requiresAuth: true, permission: 'admin_access' } }, // ... 其他路由 ]

最后，在全局路由守卫或具体的页面组件中使用这个 composable：

// 在全局路由守卫中使用 import { createRouter } from 'vue-router' import { useAuth } from '@/composables/useAuth' const router = createRouter({ ... }) // 注意：在 setup 外部使用需要一些技巧，通常需要在一个能访问应用上下文的函数内调用 // 更常见的做法是在路由配置的 beforeEach 守卫中直接进行权限判断 router.beforeEach((to, from) => { // ... 权限检查逻辑 }) // 在组件中使用 // MyComponent.vue import { useAuth } from '@/composables/useAuth' export default { setup() { const { hasPermission, navigateToProtected } = useAuth() const tryAccessAdmin = () => { if (hasPermission.value) { navigateToProtected({ name: 'Admin' }) } else { alert('权限不足！') } } return { tryAccessAdmin } } }

通过将权限逻辑封装成一个 composable，我们在任何组件里都可以方便地复用用户状态检查、权限验证和受保护导航的功能，代码非常清晰。

5. 避坑指南与最佳实践

用了这么久useRouter和useRoute，我也总结了一些容易出错的地方和让代码更健壮的建议。

第一坑：响应式丢失。直接解构route对象会导致其失去响应性！这是一个非常常见的错误。

// ❌ 错误做法：响应式丢失！ const { params, query } = useRoute() // 此时 params.id 和 query.page 不再是响应式的 // ✅ 正确做法：使用 toRefs 或直接通过 route. 访问 import { toRefs } from 'vue' const route = useRoute() // 方法A：使用 toRefs 保持响应性 const { params, query } = toRefs(route) console.log(params.value.id) // 注意访问 .value // 方法B：直接使用 route.params（推荐，最简单） const userId = computed(() => route.params.id) const page = computed(() => route.query.page)

第二坑：参数类型。从route.params或route.query获取到的值永远是字符串或字符串数组。如果你期望一个数字类型的ID，记得手动转换。

const route = useRoute() // 假设访问 /user/123 const userId = route.params.id // 类型是 string '123' const userIdAsNumber = parseInt(route.params.id, 10) // 转换为 number 123 // 或者使用计算属性 const userId = computed(() => parseInt(route.params.id, 10))

第三坑：命名路由与 params。前面提过，但值得再强调一遍：使用params传参时，必须配合name使用，不能和path混用。而query则没有这个限制。

最佳实践建议：

1. 优先使用命名路由：在router.push或<router-link>中，尽量使用name而不是path。这样即使你后期修改了路由的path，所有跳转的逻辑都不需要改动，维护性大大提升。
2. 将路由逻辑提取为 Composables：对于复杂的、涉及多个路由参数交互的页面（如上面提到的列表页），强烈建议把更新查询参数、获取数据、同步状态到URL的逻辑封装成一个独立的 composable 函数，比如useQueryPagination。这样可以在多个列表页面复用。
3. 善用路由元信息（meta）：route.meta是一个存放路由自定义信息的好地方，比如页面标题、权限要求、是否需要缓存等。你可以在全局导航守卫或组件内访问它，实现统一的逻辑处理。
4. 考虑使用路由的props传参：在定义路由时，可以设置props: true，将params作为组件的props传入。这样组件就可以像使用普通props一样使用路由参数，解耦了组件对useRoute的直接依赖，使组件更容易测试和复用。
5. 处理未匹配的路由：别忘了定义一个捕获所有路由或 404 页面（path: '/:pathMatch(.*)*'），给用户一个友好的提示，而不是一个空白页或控制台错误。

路由管理是现代前端应用的核心之一，从 Options API 的this.$router/$route过渡到 Composition API 的useRouter/useRoute，不仅仅是 API 的替换，更是思维模式的转变。它鼓励我们将与路由相关的逻辑更清晰、更模块化地组织起来。刚开始可能会觉得有点绕，但一旦熟悉了这种“函数式”的写法，你就会发现代码的灵活性和可读性都有了质的飞跃。多动手写几个例子，把上面提到的场景都实践一遍，很快你就能得心应手了。