router.push 是 Vue Router 中用于编程式导航的核心方法，它允许你在 JavaScript 代码中导航到不同的路由。以下是关于 router.push 的全面指南：
基本用法
1. 路径字符串
// 简单路径
router.push('/home')
// 带查询参数
router.push('/home?user=admin')
// 带 hash
router.push('/home#section1')
2. 描述地址的对象
// 基本对象形式
router.push({
path: '/home'
})
// 带命名路由
router.push({
name: 'user',
params: { id: '123' }
})
// 带查询参数
router.push({
path: '/register',
query: { plan: 'private' }
})
// 组合使用
router.push({
name: 'user',
params: { id: '123' },
query: { from: 'home' },
hash: '#profile'
})
参数说明
属性类型说明pathstring路由路径 (与 name 二选一)namestring命名路由 (与 path 二选一)paramsobject动态路由参数 (仅与 name 配合使用)queryobjectURL 查询参数hashstringURL hashreplaceboolean是否替换当前历史记录 (默认 false)forceboolean强制刷新相同路由 (默认 false)
特殊用法
1. 替换当前路由 (不添加历史记录)
router.push({ path: '/home', replace: true })
// 或使用 router.replace
router.replace('/home')
2. 强制刷新相同路由
router.push({ path: '/current', force: true })
3. 导航到相对路径
// 假设当前路径是 /user/123/profile
router.push('posts') // → /user/123/posts
router.push('../info') // → /user/123/info
router.push('/about') // → /about
返回值与错误处理
router.push 返回一个 Promise：
router.push('/dashboard')
.then(() => {
// 导航成功
})
.catch((error) => {
if (error.name === 'NavigationDuplicated') {
// 重复导航到相同路由
} else {
// 其他错误
}
})
组件内使用
在组件中，可以通过 this.$router 访问路由实例：
export default {
methods: {
goToUser() {
this.$router.push({
name: 'user',
params: { id: this.userId }
})
}
}
}
在组合式 API 中：
import { useRouter } from 'vue-router'
export default {
setup() {
const router = useRouter()
const navigate = () => {
router.push('/about')
}
return { navigate }
}
}
注意事项
params 与 path 不能同时使用：
// 错误 - params 会被忽略
router.push({ path: '/user/123', params: { id: '456' } })
// 正确 - 使用 name
router.push({ name: 'user', params: { id: '123' } })
动态路由参数必须完整：
// 假设路由定义为 /user/:id
router.push({ name: 'user', params: { id: '123' } }) // 正确
router.push({ name: 'user' }) // 错误 - 缺少 id 参数
导航守卫会影响跳转：
全局守卫 (beforeEach 等)路由独享守卫 (beforeEnter)组件内守卫 (beforeRouteEnter 等)
Hash 模式与 History 模式：
行为一致，但 URL 表现形式不同History 模式需要服务器配置支持
最佳实践
优先使用命名路由：
// 优于直接使用路径
router.push({ name: 'user-profile', params: { id: user.id } })
封装导航逻辑：
// utils/navigation.js
export const navigateToUser = (userId) => {
return router.push({
name: 'user',
params: { id: userId }
})
}
处理重复导航错误：
router.push('/home').catch(err => {
if (!err.name.includes('NavigationDuplicated')) {
console.error(err)
}
})
组合式 API 封装：
// composables/useNavigation.js
export function useNavigation() {
const router = useRouter()
const safePush = (to) => {
return router.push(to).catch(err => {
if (err.name !== 'NavigationDuplicated') {
throw err
}
})
}
return { safePush }
}
通过合理使用 router.push，你可以构建灵活且可维护的 Vue 应用导航系统。