Vue Router 查询参数双重编码问题解析与解决方案

问题现象

在Vue Router项目中使用路由跳转时，开发者发现查询参数(Query Parameters)的编码行为存在不一致性。当开发者手动对参数值进行URI编码后，这些值会在最终生成的URL中被二次编码，导致参数值无法正确解析。

典型场景表现为：

• 未编码参数 {name} 能正确显示为 {name}
• 手动编码后的参数 encodeURIComponent('{name}') 本应生成 %7Bname%7D，却变成了 %257Bname%257D（即编码了两次）

技术背景

URL编码(Percent-encoding)是Web开发中的基础概念，它将特殊字符转换为%后跟两位十六进制数的形式。在查询参数中，大括号{}、引号""等特殊字符通常需要编码以确保URL的有效性。

Vue Router内部实现了自己的编码/解码逻辑，目的是：

1. 保持URL的可读性
2. 确保特殊字符能正确传递
3. 处理复杂数据结构作为查询参数的情况

问题根源分析

通过查看Vue Router源码可以发现，其内部会对所有查询参数值执行强制编码操作。当开发者预先编码了参数值后，这些值会经历：

1. 开发者手动编码（如 {name} → %7Bname%7D）
2. Vue Router自动编码（%7Bname%7D → %257Bname%257D）

这种双重编码机制导致了最终URL不符合预期。尤其当参数值是JSON字符串时，问题更为明显：

• 初始值：{"order":"123"}
• 一次编码：%7B%22order%22:%22123%22%7D
• 二次编码：%257B%2522order%2522:%2522123%2522%257D

解决方案

方案一：避免预编码

最简单的解决方法是不要预先编码参数值，让Vue Router统一处理编码逻辑：

router.push({
  query: { 
    filter: '{"order":"123"}' // 直接传递原始值
  }
});

方案二：使用qs库处理复杂参数

对于需要处理复杂数据结构的情况，推荐使用成熟的qs库：

import qs from 'qs'

const router = createRouter({
  // 其他配置...
  parseQuery: qs.parse,
  stringifyQuery: qs.stringify,
})

qs库提供了更完善的查询字符串处理能力，能正确处理：

• 嵌套对象
• 数组参数
• 特殊字符编码
• 自定义序列化规则

方案三：自定义编码函数

如需更精细控制，可以实现自定义的编码逻辑：

function customStringifyQuery(query) {
  return Object.keys(query)
    .map(key => `${key}=${query[key]}`)
    .join('&')
}

const router = createRouter({
  // 其他配置...
  stringifyQuery: customStringifyQuery
})

最佳实践建议

1. 简单参数：直接传递原始值，让路由统一编码
2. JSON数据：建议使用qs库处理
3. 特殊需求：考虑自定义编码函数
4. URL共享：确保生成的URL在各种环境下都能正确解析
5. 调试技巧：使用decodeURIComponent()检查编码结果

总结

Vue Router的查询参数编码机制虽然提供了便利性，但在特定场景下可能导致双重编码问题。理解其内部工作原理后，开发者可以根据实际需求选择合适的解决方案。对于大多数项目，结合qs库使用能提供最稳定可靠的查询参数处理能力。