history.pushState() 和 replaceState() 的 state 参数可将数据附着在历史记录中,不暴露于URL、不刷新丢失,但仅限当前会话;支持结构化克隆的多种类型,不支持函数等;需安全读取 history.state 并监听 popstate 事件获取真实状态。

直接用 history.pushState() 或 replaceState() 的第一个参数存对象,就能把数据“附着”在历史记录上,不暴露在 URL 里,用户看不到,刷新也不会丢失(只要没离开当前会话)。
state 参数就是专为这事设计的
它不是 URL 查询参数,也不是 cookie,更不走网络请求——纯前端内存级绑定。浏览器内部用结构化克隆算法保存,支持 Date、Array、Object、Map、Set 等类型(现代浏览器),但不能传函数、Symbol、Promise 或 window 对象,这些会被静默忽略。
- 推荐写法:
history.pushState({ formData: { name: 'Alice' }, step: 2 }, '', '/checkout') - 标题参数(第二个)目前无实际作用,传空字符串或简短描述都行
- URL 参数(第三个)决定地址栏显示什么,和 state 内容完全解耦
读取时必须等对时机
history.state 只返回当前历史项的状态对象,但它在页面首次加载时是 null——因为初始页没被 pushState 或 replaceState 主动设置过状态。别一上来就解构,容易报错。
- 安全读法:先判断
if (history.state) { /* 使用 */ } - 监听导航变化要用
popstate事件,不是每次跳转都触发,只在点击后退/前进、调用history.back()等“回到已有记录”行为时才派发 -
popstate的event.state才是目标页的真实状态,比直接读history.state更可靠
避免常见陷阱
很多人以为 state 是全局共享或自动同步的,其实它严格绑定到每个历史条目。同一个 URL 可以有多个不同 state 的记录,比如表单填一半点后退,再前进,状态还在;但手动刷新页面,history.state 就变 null 了(除非服务端注入或脚本主动 replaceState)。
- 不要依赖 state 做持久化存储:关闭标签页、硬刷新、从外部链接进入,state 都会消失
- 敏感数据别全放 state:虽然不显式出现在 URL,但仍在内存中,DevTools 可查
- 想跨标签/跨会话保留?得配合
localStorage或sessionStorage做兜底
搭配 replaceState 更新当前状态
如果只是想更新当前页的状态(比如表单实时保存),不用新增历史记录,就用 replaceState:
history.replaceState({ ...oldState, draft: true }, '', location.pathname)- 它不会增加新条目,也不影响后退按钮逻辑,适合微调当前页上下文
- 注意:调用后
history.state会立即更新,但popstate不会触发

















