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'
})

参数说明

特殊用法

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 }
  }
}

注意事项

1. ​params 与 path 不能同时使用​：

   // 错误 - params 会被忽略
   router.push({ path: '/user/123', params: { id: '456' } })
   
   // 正确 - 使用 name
   router.push({ name: 'user', params: { id: '123' } })

2. ​动态路由参数必须完整​：

   // 假设路由定义为 /user/:id
   router.push({ name: 'user', params: { id: '123' } }) // 正确
   router.push({ name: 'user' }) // 错误 - 缺少 id 参数

3. ​导航守卫会影响跳转​：

   • 全局守卫 (beforeEach 等)
   • 路由独享守卫 (beforeEnter)
   • 组件内守卫 (beforeRouteEnter 等)

4. ​Hash 模式与 History 模式​：

   • 行为一致，但 URL 表现形式不同
   • History 模式需要服务器配置支持

最佳实践

1. ​优先使用命名路由​：

   // 优于直接使用路径
   router.push({ name: 'user-profile', params: { id: user.id } })

2. ​封装导航逻辑​：

   // utils/navigation.js
   export const navigateToUser = (userId) => {
     return router.push({
       name: 'user',
       params: { id: userId }
     })
   }

3. ​处理重复导航错误​：

   router.push('/home').catch(err => {
     if (!err.name.includes('NavigationDuplicated')) {
       console.error(err)
     }
   })

4. ​组合式 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 应用导航系统。