replaceState 不能直接改 query 参数，因其只更新 URL 字符串而不感知 query 语义，需用 URL 构造函数安全拼接完整 URL 并传入绝对路径。
replaceState 为什么不能直接改 query 参数
直接调用 history.replaceState 修改 URL 中的 ?a=1&b=2 部分，浏览器不会报错，但后续点击浏览器「后退」时可能跳转到一个并不存在的路径（比如原始 URL 根本没带参数），导致状态错乱。根本原因是：replaceState 只负责更新当前历史项的 state 和 URL 字符串，它不感知 query 的语义，也不会帮你 diff 或 merge 参数。
所以必须自己拼接完整 URL，不能只传入新参数对象。
- 错误做法：
history.replaceState(null, '', '?x=3')—— 这会把整个 URL 变成https://example.com/?x=3，丢掉 pathname 和原有参数 - 正确思路：从
window.location拿出origin + pathname，再手动构造 query 字符串 - 注意
replaceState第三个参数必须是**绝对 URL**（或相对于当前页的路径），相对路径如'?x=3'在子目录下会出错
如何安全拼接新 query 并保留 pathname
最简健壮的做法是基于 URL 构造函数操作，避免手撕字符串。它能自动处理编码、重复键、空值等边界情况。
function updateQuery(params) {
const url = new URL(window.location);
Object.entries(params).forEach(([k, v]) => {
if (v == null) {
url.searchParams.delete(k);
} else {
url.searchParams.set(k, v);
}
});
history.replaceState(null, '', url.toString());
}
- 用
url.searchParams.set()而不是append()，避免参数重复累积 -
v == null同时覆盖null和undefined，删参更稳妥 - 如果项目不支持
URLAPI（IE），需 fallback 到正则解析，但现代项目基本不用考虑
state 参数该存什么、什么时候需要它
replaceState 的第一个参数（state）不是可有可无的占位符。它决定了用户点「后退/前进」时你能拿到什么数据。
- 必须存和当前 URL query 强相关的状态，比如
{ tab: 'log', page: 3, filter: 'error' } - 不要存 DOM 引用、函数或未序列化的对象 —— 它会被序列化为 JSON，且页面重载后丢失
- 如果只用 URL query 恢复状态（比如 React Router 的
useSearchParams），state可设为null；但如果要监听popstate手动响应，就必须存一份镜像 - 常见坑：两次
replaceState传了不同state，但没监听popstate，导致后退时 UI 没更新
replaceState 后如何避免重复触发 popstate
调用 replaceState 不会触发 popstate，这点和 pushState 一致。但很多人误以为它会，于是加了防抖或 flag 控制，反而让逻辑变复杂。
- 真正会触发
popstate的只有用户点击浏览器前进/后退按钮，或调用history.back()等导航方法 - 如果你在
popstate回调里也调用了replaceState（比如修正非法参数），记得检查event.state是否为空，避免无限循环 - React/Vue 场景下，优先用路由库的
useNavigate或$router.replace，它们已封装好 state 同步和事件隔离
最易被忽略的是：replaceState 不会改变 document.title，如果你靠 URL 参数控制标题，得手动同步 document.title = 'xxx'；另外，服务端渲染（SSR）场景下，仅靠 replaceState 无法让首次加载就匹配参数，仍需服务端或 hydration 阶段读取 URL 并初始化状态。
