一、前言：为什么要学习 Vue Router？

在单页面应用(SPA)开发中，路由管理是核心功能之一。Vue Router 作为 Vue.js 官方推荐的路由解决方案，与 Vue.js 深度集成，提供了以下重要功能：

• 页面无刷新跳转：保持应用状态的同时切换视图
• 嵌套路由：构建复杂的页面布局结构
• 路由守卫：控制导航权限和逻辑
• 动态路由：根据需求加载路由配置
• 滚动行为控制：提升用户体验

本教程将使用 Vue 3 的 Composition API 和 <script setup> 语法糖，这是目前最推荐的使用方式，代码更简洁，逻辑更清晰。

二、环境准备：创建带路由的 Vue 项目

对于初学者，推荐使用 Vite 创建 Vue 项目：

npm create vite@latest my-vue-app --template vue
cd my-vue-app
npm install vue-router@4
npm run dev

三、基础路由配置详解

1. 创建路由实例

在 src/router/index.js 中：

import { createRouter, createWebHistory } from 'vue-router'
import HomeView from '../views/HomeView.vue'// 定义路由配置
const routes = [{path: '/',  // 访问路径name: 'home', // 路由名称（可选但推荐）component: HomeView // 对应的组件},{path: '/about',name: 'about',// 路由懒加载（性能优化）component: () => import('../views/AboutView.vue')}
]// 创建路由实例
const router = createRouter({history: createWebHistory(import.meta.env.BASE_URL), // 使用HTML5 history模式routes // 注入路由配置
})export default router

2. 在主文件中安装路由

src/main.js 中：

import { createApp } from 'vue'
import App from './App.vue'
import router from './router' // 导入路由配置const app = createApp(App)app.use(router) // 使用路由插件app.mount('#app')

3. 在 App.vue 中添加路由视图

<script setup>
// 这里可以导入需要的组件或逻辑
</script><template><header><!-- 导航链接 --><nav><router-link to="/">首页</router-link><router-link to="/about">关于</router-link></nav></header><!-- 路由匹配的组件将渲染在这里 --><router-view></router-view>
</template><style>
/* 基础样式 */
.router-link-active {font-weight: bold;
}
</style>

四、编程式导航的三种常用方式

1. 字符串路径

最简单直接的跳转方式：

<script setup>
import { useRouter } from 'vue-router'const router = useRouter()const goToAbout = () => {router.push('/about') // 直接使用路径字符串
}
</script><template><button @click="goToAbout">关于我们</button>
</template>

2. 命名路由（推荐）

使用路由配置中的 name 属性，更易于维护：

<script setup>
import { useRouter } from 'vue-router'const router = useRouter()const goToHome = () => {router.push({ name: 'home' }) // 使用路由名称
}
</script>

3. 带参数的对象形式

最灵活的方式，可以添加各种参数：

<script setup>
import { useRouter } from 'vue-router'const router = useRouter()const goToUserProfile = () => {router.push({name: 'user', // 路由名称params: { id: 123 }, // 路径参数query: { tab: 'profile' }, // 查询参数hash: '#contact' // 哈希值})
}
</script>

五、路由传参的三种方法对比

1. params 传参（动态路由）

适用场景：参数是路径的一部分，如 /user/123

路由配置：

{path: '/user/:id', // 动态路径参数name: 'user',component: UserView
}

跳转方法：

router.push({ name: 'user', params: { id: 123 } })

接收参数：

<script setup>
import { useRoute } from 'vue-router'const route = useRoute()
const userId = route.params.id // 123
</script>

2. query 传参（查询参数）

适用场景：可选参数，如 /search?q=vue

跳转方法：

router.push({path: '/search',query: { q: 'vue', page: 1 }
})

接收参数：

<script setup>
import { useRoute } from 'vue-router'const route = useRoute()
const searchQuery = route.query.q // 'vue'
const pageNum = route.query.page // '1' (注意是字符串)
</script>

3. props 传参（最推荐）

优点：组件不直接依赖路由，更易于复用

路由配置：

{path: '/product/:id',name: 'product',component: ProductView,props: true // 将params转为props// 或者使用函数形式更灵活// props: route => ({ id: route.params.id, query: route.query })
}

组件接收：

<script setup>
defineProps({id: {type: String,required: true}
})
</script>

六、导航守卫实战

1. 全局前置守卫（常用做权限控制）

// router/index.js
router.beforeEach((to, from, next) => {const isAuthenticated = checkLoginStatus() // 你的验证逻辑if (to.meta.requiresAuth && !isAuthenticated) {// 如果需要登录且未登录，跳转到登录页next({ name: 'login' })} else if (to.name === 'login' && isAuthenticated) {// 如果已登录又访问登录页，跳转到首页next({ name: 'home' })} else {// 正常放行next()}
})

2. 组件内守卫（处理未保存更改等场景）

<script setup>
import { onBeforeRouteLeave } from 'vue-router'const unsavedChanges = ref(false)// 用户尝试离开时提示
onBeforeRouteLeave((to, from, next) => {if (unsavedChanges.value) {const confirmLeave = confirm('您有未保存的更改，确定要离开吗？')if (confirmLeave) {next()} else {next(false) // 取消导航}} else {next()}
})
</script>

七、常见问题解决方案

1. 路由重复导航错误

router.push('/some-path').catch(err => {if (err.name !== 'NavigationDuplicated') {// 如果不是重复导航错误，抛出其他错误throw err}
})

2. 响应式监听路由参数变化

<script setup>
import { useRoute } from 'vue-router'
import { watch } from 'vue'const route = useRoute()// 监听id参数变化
watch(() => route.params.id,(newId) => {if (newId) {fetchData(newId) // 重新获取数据}},{ immediate: true } // 立即执行一次
)
</script>

八、最佳实践建议

1. 路由命名：始终为路由设置 name 属性，便于维护
2. 懒加载：路由组件尽量使用 () => import() 语法
3. 参数传递：优先使用 props 方式，提高组件复用性
4. 导航守卫：合理使用，避免过度复杂的逻辑
5. 错误处理：对可能失败的导航添加错误处理

九、总结

通过本教程，你应该已经掌握了：

✅ Vue Router 的基本配置方法
✅ 编程式导航的各种使用场景
✅ 三种路由传参方式及适用情况
✅ 导航守卫的实际应用
✅ 常见问题的解决方案

路由是 Vue 单页面应用的核心，建议初学者多动手实践，尝试不同的配置和跳转方式。遇到问题时，可以查阅 Vue Router 官方文档 获取最新信息。

如果有任何疑问，欢迎在评论区留言讨论！