Vue Router 页面跳转时怎么保留查询参数？

做 Vue 项目时，经常遇到这样的情况：列表页选了筛选条件（比如搜索关键词、分类），点进详情页再返回，筛选条件全没了；或者多 Tab 页面切换，刷新后 Tab 状态丢了，想要让 URL 里的查询参数（query params）在页面跳转、刷新时都能保留，得怎么操作？这篇从场景、实现方法到避坑技巧，一步步讲清楚。

先搞懂：为什么要保留查询参数？

先看几个你肯定遇到过的场景：

• 列表页筛选记忆：商品列表页选了“价格从高到低”“数码分类”，点进商品详情再返回，希望这些筛选条件还在，不用重新选；
• 页面状态持久化：多语言切换（?lang=en）、暗黑模式（?theme=dark）用 query 参数存状态，刷新页面后状态不变；
• 分享链接还原：把带筛选条件的页面分享给同事，对方打开链接后，页面能自动还原当时的筛选状态。

这些场景的核心需求是：让 URL 里的 query 参数在导航、刷新时“不掉线”——既提升用户体验，又能实现页面状态的持久化。

Vue Router 默认咋处理 query 参数？

先明白默认行为,才知道哪里需要“插手”。

假设现在在列表页,URL 是 /list?search=vue&cat=front，点一个 <router-link to="/detail/123"> 跳转到详情页，这时候：

• 详情页的 URL 是 /detail/123（query 参数被清空）；
• 点浏览器返回按钮回到列表页,URL 还是 /list?search=vue&cat=front（因为历史记录里存了列表页的原始 URL）。

哎,这时候返回列表页 query 是保留的啊？那什么时候会丢？

关键在“主动跳转”：如果在详情页里，用 this.$router.push('/list') 跳回列表页（不带 query），这时候新的列表页 URL 是 /list（query 没了），历史记录变成 [列表页(带 query)、详情页、列表页(不带 query)]，再点返回，先到详情页，再返回就到“不带 query 的列表页”了——这时候 query 就丢了。

默认行为下，只有“浏览器返回/前进”会保留历史记录里的 query；但如果用代码主动跳转（且没传 query），query 会被覆盖。

声明式导航（<router-link>）咋保留 query？

声明式导航靠 <router-link> 的 to 属性传参，分两种场景处理：

跳转时，把当前页的 query 全传给目标页

比如列表页跳详情页,希望返回时列表页的 query 还在，可以把列表页的 query“捎带”给详情页：

<!-- 列表页组件 -->
<router-link 
  :to="{ 
    name: 'Detail', 
    params: { id: 123 }, 
    query: $route.query 
  }"
>去详情页</router-link>

这样,详情页的 URL 会变成 /detail/123?search=vue&cat=front，等从详情页返回列表页（点浏览器返回按钮），列表页的 URL 还是带 query 的——因为历史记录里存了原始列表页的 URL。

好处：简单直接，不用额外逻辑；
缺点：目标页（详情页）的 URL 会带一堆它用不上的参数，可能影响美观或 SEO。

只保留部分 query 参数

如果列表页有 search（搜索关键词）和 cat（分类）两个参数，但只需要保留 search，可以这么做：

<router-link 
  :to="{ 
    name: 'Detail', 
    params: { id: 123 }, 
    query: { search: $route.query.search } 
  }"
>去详情页</router-link>

这样详情页的 URL 是 /detail/123?search=vue，返回列表页时，search 参数还在，cat 参数可能因为其他操作变化（但这里只保 search）。

编程式导航（router.push/router.replace）咋保留 query？

编程式导航（比如按钮点击后用 this.$router.push 跳转）和声明式逻辑类似，核心是在跳转时主动传 query。

传递当前页的全部 query

列表页里写个方法,跳转到详情页时带 query：

// 列表页组件方法
goToDetail() {
  this.$router.push({
    name: 'Detail',
    params: { id: 123 },
    query: this.$route.query // 把当前页的 query 全传过去
  })
}

传递部分 query + 新增参数

比如不仅保留 search，还要给详情页加个 from 标记（表示从列表页跳转来的）：

goToDetail() {
  this.$router.push({
    name: 'Detail',
    params: { id: 123 },
    query: { 
      search: this.$route.query.search,
      from: 'list' // 新增参数
    } 
  })
}

用 router.replace 替换历史记录（谨慎用）

如果希望“跳转到目标页后，返回时直接跳过当前页”，可以用 router.replace（替换当前历史记录）：

goToDetail() {
  this.$router.replace({
    name: 'Detail',
    params: { id: 123 },
    query: this.$route.query
  })
}

但这样做,返回时不会回到“带 query 的列表页”，而是更前一个页面，所以只有确定不需要保留返回路径时才用。

路由守卫：全局/局部拦截，自动保留 query

如果很多页面都需要保留 query，每个导航都写 query: $route.query 太麻烦，这时候用路由守卫批量处理。

全局前置守卫（router.beforeEach）

在路由初始化文件（router/index.js）里，给所有跳转到详情页的导航自动加 query：

// router/index.js
const router = new VueRouter({ ... })
router.beforeEach((to, from, next) => {
  // 如果目标路由是详情页，把当前页（from）的 query 合并过去
  if (to.name === 'Detail') {
    to.query = { ...from.query, ...to.query }
  }
  next() // 必须调用 next() 放行
})

注意：Vue Router 3.x 中 to.query 可以直接修改；Vue Router 4.x（Vue 3 用）中 to 是只读的，得换方式（比如用 next({ ...to, query: { ... } })）。

路由独享守卫（beforeEnter）

如果只有某几个路由需要保留 query，给路由单独加守卫：

// router/index.js
const routes = [
  {
    path: '/detail/:id',
    name: 'Detail',
    component: Detail,
    beforeEnter: (to, from, next) => {
      to.query = { ...from.query, ...to.query }
      next()
    }
  }
]

这样,只要跳转到详情页，都会自动带上当前页的 query，不用每个 <router-link> 或 router.push 都写 query。

进阶：query 参数的“清理”与“合并”

保留 query 不是一股脑全传，还要考虑参数冗余和临时参数处理。

合并 query：保留需要的，覆盖不要的

比如当前页（列表）的 query 是 { search: 'vue', cat: 'front' }，目标页（详情）自己的 query 是 { tab: 'comments' }，希望合并成 { search: 'vue', cat: 'front', tab: 'comments' }，可以用对象展开：

// 合并时，from 的 query 在前，to 的 query 在后（to 的参数会覆盖 from 的重复参数）
to.query = { ...from.query, ...to.query }
// 或者反过来，to 的 query 在前，from 的 query 覆盖 to 的
to.query = { ...to.query, ...from.query }

清理临时参数：让 URL 更干净

比如详情页的 query 带了 from: 'list'（仅用于标记来源，不需要显示在 URL），可以在详情页加载后，用 router.replace 去掉：

// 详情页组件
mounted() {
  const { from, ...restQuery } = this.$route.query
  if (from) { // 如果有 from 参数，就清理掉
    this.$router.replace({
      query: restQuery
    })
  }
}

这样,详情页的 URL 会从 /detail/123?search=vue&from=list 变成 /detail/123?search=vue，历史记录也被替换，返回列表页时不影响。

常见坑点与解决方案

踩过这些坑,才能真正用好 query 参数：

坑：跳转后 query 丢了，返回页面状态不对

原因：用 router.push('/xxx') 跳转时没传 query，覆盖了历史记录里的 query。
解决：跳转时主动传 query（如 query: this.$route.query），或用 router.back() 返回（利用历史记录的原始 query）。

坑：URL 里 query 参数太多，显得杂乱

原因：传递了不必要的参数到目标页。
解决：只传需要的参数（如 query: { search: $route.query.search }），或在目标页加载后清理临时参数。

坑：刷新页面后 query 参数丢了

原因：query 参数没写到 URL 里（比如用 Vuex 存了状态，但没同步到 URL）。
解决：确保需要保留的参数在 URL 的 query 中，页面加载时从 $route.query 读参数初始化状态。

坑：多 Tab 切换，query 不同步

场景：页面有“商品”“评价”Tab，用 ?tab=goods 控制显示，切换 Tab 时 URL 没更新，刷新后 Tab 状态丢了。
解决：切换 Tab 时，用 router.push 更新 query：

// 切换 Tab 的方法
changeTab(tab) {
  this.$router.push({
    query: { ...this.$route.query, tab }
  })
}
// 页面加载时读 query 初始化 Tab
export default {
  data() {
    return {
      activeTab: this.$route.query.tab || 'goods'
    }
  },
  watch: {
    '$route.query.tab'(newTab) {
      this.activeTab = newTab || 'goods'
    }
  }
}

结合状态管理（Vuex/Pinia），让 query 更智能

如果页面状态复杂（比如多个筛选条件、分页），可以结合 Vuex/Pinia，让状态和 query 双向同步：

1. 状态变，query 变：修改 Vuex 里的筛选条件后，主动更新路由的 query；
2. query 变，状态变：页面加载时，从 $route.query 读参数，初始化 Vuex 状态。

示例：Vuex 同步 query

// Vuex 模块（筛选条件）
const state = {
  filters: { search: '', cat: '' }
}
const mutations = {
  SET_FILTERS(state, payload) {
    state.filters = payload
  }
}
const actions = {
  updateFilters({ commit, dispatch }, newFilters) {
    commit('SET_FILTERS', newFilters)
    // 同步到路由 query
    dispatch('router/updateQuery', newFilters, { root: true })
  }
}
// 路由的 action（全局 mixin 实现）
const routerActions = {
  updateQuery({ commit }, query) {
    router.push({ query })
  }
}

这样,修改筛选条件时，Vuex 和 URL 的 query 同时更新，页面跳转时自然能保留参数。

掌握这几点，query 参数“听话”又好用

保留 Vue Router 的 query 参数，核心是理解历史记录机制 + 主动控制 query 传递：

• 导航时传 query：用 <router-link> 的 query 属性或 router.push 的 query 配置，把需要保留的参数传过去；
• 路由守卫批量处理：全局/局部守卫自动合并 query，减少重复代码；
• 清理临时参数：用 router.replace 去掉不必要的参数，保持 URL 简洁；
• 结合状态管理：让页面状态和 query 双向同步，实现更复杂的场景。

不管是列表筛选记忆、多 Tab 状态保留，还是分享链接还原，把这些方法用起来，用户体验和开发效率都能 up～