NextJS router传query参数偶发字符编码异常导致跳转路径错误问题

%3F是问号?的URL编码格式，出现该异常的本质是路由跳转时query参数没有被NextJS Router正确识别为查询参数，反而被当做路径的一部分做了URL编码，偶发的常见诱因如下：

• 路由未就绪时触发跳转：如果调用router.push时Router实例还未完成初始化（比如App Router下组件首次渲染同步执行跳转、Pages Router下在_app挂载前逻辑调用），Router还未加载完路由配置，无法正确拆分路径和查询参数，就会把query序列化后直接拼到路径后编码
• 短时间多次跳转冲突：同一时间触发多次router.push调用，前一次跳转未完成就执行下一次，路由状态冲突导致参数拼接逻辑异常
• 自定义路由规则冲突：如果项目中配置了匹配根路径/的中间件、next.config.js重写/重定向规则，规则的边界判断有漏洞，偶发会把带query的路径错误转换为编码后的格式

• 增加埋点日志：在跳转逻辑前后打印状态，异常发生时可快速定位触发条件

console.log('跳转前 router 就绪状态：', router.isReady)
console.log('跳转入参：', { pathname: '/', query: { id: '12344567' } })
router.push({
  pathname: '/',
  query: { id: '12344567' },
}).then(() => {
  console.log('跳转完成后页面地址：', window.location.href)
}).catch(err => console.error('跳转报错：', err))

• 排查并发跳转场景：检查跳转逻辑是否存在于未做防抖的点击事件、滚动监听、异步回调中，这类场景容易出现短时间多次触发跳转的情况
• 排查自定义路由规则：临时注释根路径相关的中间件、重写/重定向规则，验证问题是否复现，排除规则冲突导致的异常

• 跳转前增加Router就绪判断：把跳转逻辑放到useEffect中，依赖router.isReady，确保Router初始化完成后再执行跳转

useEffect(() => {
  // 仅在Router就绪后执行跳转
  if (!router.isReady) return
  router.push({
    pathname: '/',
    query: { id: '12344567' },
  })
}, [router.isReady])

• 用字符串路径形式规避对象参数解析问题：直接拼接完整的跳转路径，跳过Router对对象参数的解析逻辑

router.push(`/?id=12344567`)

• 跳转逻辑增加防抖：避免短时间内多次触发路由跳转

const handleJump = debounce(() => {
  router.push({
    pathname: '/',
    query: { id: '12344567' },
  })
}, 300)

内容的提问来源于stack exchange，提问作者Brian H.