先说个我前阵子遇到的场景一个 UniApp 开发的活动 H5用户从首页进到任务列表再点进某一个活动详情页中间夹了一层分享引导页。结果用户手一滑把页面刷新了再点返回页面直接没反应再点一次退到了浏览器空白页。活动详情页里好不容易填了一半的表单全没了。这不是偶发是 UniApp 编译到 H5 之后路由栈的典型问题刷新页面时内存里的页面栈会全部清空而浏览器 history 里存的又只是一串 URL并不是 UniApp 业务层认识的那个页面栈。于是该返回的返回不了该保留的页面参数也丢了。这篇文章想解决的就是这个问题在 UniApp H5 环境里把路由栈做成可持久化的数据刷新前保存一份快照刷新后自动把页面链路重建出来。同时把我在实际项目里踩过的几个坑一并讲讲省的你再走一遍。如果你也在开发 UniApp 的 H5 页面遇到刷新后返回失灵、页面链路过深、或者被嵌在 App WebView 里需要配合外部跳转这类需求这篇的内容可以直接拿过去用。1. 刷新一下用户就回不去了H5路由栈丢失的根因1.1 业务中最常见的三种路由栈丢失现场第一种多步骤流程中断。用户在一个注册引导流里走到了第三步刷新后直接被甩回第一步甚至首页前面填过的手机号、验证码状态全部作废。这种情况在活动页和营销落地页尤为常见用户的耐心也就够刷一次页面。第二种返回按钮失灵。用uni.navigateTo跳了三层页面刷新后调用uni.navigateBack()没反应。因为页面栈只剩当前这一层了。在很多安卓 WebView 里硬件返回键也会触发同样的问题表现就是“点返回直接白屏”或者“直接退出内嵌 H5”。第三种和浏览器前进后退按钮的步调不一致。用户通过浏览器自带的返回按钮回退到上一个 URL但页面组件并没有恢复到对应的业务状态关键数据还是空界面看起来就像坏掉了。这三种现场的共同根子只有一个页面栈只存在于内存里刷新即清零。1.2 UniApp H5 的页面栈到底存在哪里如果你写过原生小程序或者 App 端 Uniapp你可能习惯了那套页面栈机制navigateTo往栈里压一个页面navigateBack弹出一个页面getCurrentPages()能拿到这个栈。但 UniApp 编译到 H5 时底层的页面栈其实是 vue-router 在管。uni.navigateTo会被映射成路由 pushuni.navigateBack映射成路由 back。vue-router 的页面栈是纯内存结构挂在当前运行的 JavaScript 上下文里。刷新页面的本质是什么呢是浏览器把当前页面的 JS 上下文整个销毁然后根据 URL 重新加载一份新的 JavaScript 上下文。新的上下文里vue-router 重新初始化getCurrentPages()只保留当前这个 URL 对应的页面。于是出现了一个很拧巴的中间态浏览器 history 本身还有之前的浏览记录你点浏览器后退按钮确实可以回到之前的 URL但 UniApp 业务层的页面栈已经不认识那些 URL 了。组件是新的、参数重新解析了、内存里的临时状态全没了就会出现“返回之后白屏”或者“返回之后数据缺失”的情况。1.3 刷新不等于 App 的重新启动为什么 localStorage 类方案不解决根因很多人第一反应是路由栈丢了那就用 localStorage 存一份刷新后再读出来呗。这个思路方向对但细节上很容易跑偏。localStorage 的特点是跨会话持久化它和浏览器标签页、会话窗口都不绑定。如果用户开了两个标签页两个标签页共用同一个 localStorage会互相覆盖路由栈导致页面栈串台。另一个问题是localStorage 的生命周期太长用户可能两周前打开过一个内嵌 H5留下一条早已过期的路由栈新版本上线后路径都变了一恢复反而恢复出一个 404 页面。sessionStorage在这方面更合适一些。它的生命周期绑定的是当前标签页的会话标签页不关闭就一直在刷新页面也不会清空但一旦用户关掉标签页数据自动销毁。这正好符合路由栈的使用场景我只关心用户在当前这次浏览会话里的页面链路而不是跨越多天之后还要恢复一个不知道哪来的旧页面。另外有人会想到用history.state或者浏览器 history 的各种 API 来恢复理论上可行但操作起来非常别扭。因为浏览器的 history 对象并不区分“业务路由栈”和“页面状态”你要做的是往里面塞很多私有标记并且还得保证 UniApp 的 vue-router 能正确识别这些标记。真做完了会发现维护成本比写一套路由栈快照高得多。2. 方案设计把存储层选对比写恢复代码更重要2.1 四种存储方案对比我最后为什么选了 sessionStorage我在设计这套方案的时候把能想到的存储载体都列了一遍逐个排除。存储方案生命周期能否跨页面主要问题全局变量页面刷新即销毁否解决不了刷新场景localStorage持久保存是标签页之间互相覆盖旧数据清理麻烦sessionStorage当前标签页会话是基本没有明显短板history.state当前 history 条目否和 vue-router 的页面栈语义不一致最终选择就是sessionStorage。它保证了刷新页面时数据不丢符合路由恢复的需求关闭标签页自动清空不会留下长期脏数据数据只在当前标签页内有效两个标签页互不干扰一个额外的考虑是兼容性。UniApp 的 H5 端一般运行在微信内置浏览器、App WebView、常规浏览器里这些环境对 sessionStorage 的支持已经非常成熟不需要担心降级问题。即使遇到极端情况某些私密浏览模式会限制写入我们只要在读写时加上 try/catch失败就跳过持久化不影响正常路由跳转。2.2 路由栈里的数据模型只存能序列化的最小字段确定了存储层接下来的问题就变成了路由栈这个快照到底应该存什么最憨的做法是把getCurrentPages()返回的整个数组直接 JSON.stringify 存进去。但你会发现getCurrentPages()返回的是页面实例里面包含了组件实例、DOM 引用、事件绑定等等一大堆无法序列化的对象强行序列化要么失败要么存进去的是循环引用的报错。我把每个页面抽象成最小的两个字段{ route: pages/activity/detail, options: { id: 10086, from: share } }route用来定位页面路由options存放跳转时携带的参数。这两个字段已经足够在刷新后恢复出一个页面了。页面内部的滚动位置、表单内容不应该放在路由栈这一层那是页面级状态持久化的事后面第五部分会讲。还有一个细节值得注意getCurrentPages()返回的页面实例上route字段是不带斜杠的形如pages/activity/detail。而uni.navigateTo和uni.reLaunch接收的 URL 需要带上前置斜杠形如/pages/activity/detail。在保存和恢复之间需要做一次统一的格式转换这个坑很容易埋得无声无息。2.3 监听策略与其手写每个路由 API不如信任 getCurrentPages()理论上路由栈的变化无非就是增删改navigateTo对应压栈navigateBack对应弹栈redirectTo对应替换栈顶reLaunch对应清空重建。但实际情况远没有这么干净。用户在页面里触发的事件、第三方 SDK 引导的跳转、浏览器前进后退按钮、WebView 外部注入跳转……任何一个分支没覆盖到持久化栈就和真实页面栈不一致。与其把所有路由 API 封装一层做拦截不如换个思路getCurrentPages()本来就是当前页面栈的真实快照我只需要在每次“路由变化完成后”读取一次它再序列化保存到 sessionStorage 里就行。UniApp 提供了一个比较合适的钩子uni.onAppRouteComplete会在路由跳转完成之后触发。这个时机正好是页面栈刚完成增删之后。考虑到这个 API 是 HBuilderX 3.3.7 以后才提供的如果项目版本较老也可以用每个页面的onShow来触发保存或者直接在 vue-router 的afterEach里做同样的事。这种“每次变化都存一份全量快照”的设计写起来很简单也不容易漏虽然数据有冗余但路由栈的数据量本身很小完全在可接受范围内。工程上简单可靠往往比精巧更重要。3. 核心实现路由栈快照与刷新后的逐级重建3.1 route-stack.js一个独立的持久化模块先把路由栈的读写封装成一个独立模块方便在 App.vue、页面和后续扩展中统一调用。// utils/route-stack.js const STORAGE_KEY UNI_H5_ROUTE_STACK_V1 const STACK_LIMIT 10 export function getRouteStack() { try { const data sessionStorage.getItem(STORAGE_KEY) return data ? JSON.parse(data) : [] } catch (e) { return [] } } export function saveRouteStack() { try { const pages getCurrentPages() const stack pages.map(page ({ route: page.route || page.$page?.fullPath, options: page.options || {} })) // 只保留最近 10 层防止极端情况下栈数据无限膨胀 sessionStorage.setItem(STORAGE_KEY, JSON.stringify(stack.slice(-STACK_LIMIT))) } catch (e) { // 存储失败时静默处理不影响路由跳转 } } export function clearRouteStack() { try { sessionStorage.removeItem(STORAGE_KEY) } catch (e) {} } export function buildPageUrl(item) { const route item.route.startsWith(/) ? item.route : /${item.route} const query Object.keys(item.options || {}) .map(key ${encodeURIComponent(key)}${encodeURIComponent(item.options[key])}) .join() return query ? ${route}?${query} : route }几个关键选择STORAGE_KEY里我加了_V1后缀这是一开始就要养成的习惯。以后如果字段结构变了直接改成_V2旧版本遗留的脏数据自动作废不用写一堆迁移逻辑。page.$page?.fullPath是 H5 端比较有用的兜底。某些情况下page.route拿到的值不够准确而$page.fullPath会带上完整路径和参数双保险。STACK_LIMIT设成 10是因为 UniApp App 端的页面栈本身有限制H5 端虽然理论上可以更多但过深的页面栈对浏览器内存不友好超过 10 层的多级跳转大概率是业务设计上出了问题。3.2 App.vue 里接入路由监听与恢复接下来在 App.vue 里做两件事注册路由变化监听处理刷新后的恢复逻辑。// App.vue import { getRouteStack, saveRouteStack, clearRouteStack, buildPageUrl } from /utils/route-stack.js export default { onLaunch() { // 每次路由跳转完成重新保存一份路由栈快照 this.isRestoring false if (uni.onAppRouteComplete) { uni.onAppRouteComplete(() { if (this.isRestoring) return saveRouteStack() }) } }, onShow() { // 利用 onShow 时机判断是否需要恢复路由栈 this.tryRestoreRouteStack() }, methods: { tryRestoreRouteStack() { // 防止重复恢复 if (this.isRestoring) return const savedStack getRouteStack() const currentPages getCurrentPages() // 只有当前栈里只有一个页面时才尝试恢复避免和正常跳转打架 if (savedStack.length 2 || currentPages.length ! 1) { return } this.isRestoring true // 给首次渲染留一点时间避免页面还没进入稳定状态就开始跳转 setTimeout(() { this.restoreStack(savedStack) }, 300) }, restoreStack(stack) { let index 0 // 递归跳转每次成功后再跳下一个避免并发 navigateTo 导致页面栈错乱 const step () { if (index stack.length) { this.isRestoring false saveRouteStack() return } const item stack[index] const url buildPageUrl(item) index 1 // 第一层用 reLaunch后面的页面用 navigateTo if (index 1) { uni.reLaunch({ url, success: () setTimeout(step, 200) }) } else { uni.navigateTo({ url, success: () setTimeout(step, 200) }) } } step() } } }3.3 恢复函数的关键细节为什么第一层用 reLaunch为什么逐级跳恢复逻辑看起来只有十几行但每一处都有讲究。第一层用reLaunch而不是navigateTo的原因是刷新后浏览器 URL 指向的是栈里最后一个页面直接navigateTo会在当前页面之上再压一个页面最后重建出来的栈会多出一层。用reLaunch先清空当前页面再跳转到真正的栈底页面这样重建出来的页面栈结构和刷新前是完全一致的。逐级navigateTo而不是一次发多个跳转的原因更直接uni.navigateTo是异步的底层依赖 vue-router 的 push 操作。如果连续快速调用多次跳转请求不会按顺序入栈可能出现后一个跳转覆盖掉前一个的情况最终页面栈只剩最后一个页面。我加了 200ms 的延时这个值不是拍脑袋定的。UniApp H5 页面首次渲染需要经过组件创建、数据加载、DOM 挂载几个阶段200ms 可以让上一层的onLoad和基本渲染先完成再触发下一层跳转。如果你的页面里有较重的数据请求这个值建议调到 300ms 以上。这里还有一个坑恢复期间的每次跳转都会触发uni.onAppRouteComplete如果不做拦截脚本会把重建过程中的中间态又存成新的路由栈导致后面再刷新时拿到的栈比真实栈少一层或者多一层。所以在跳转前把this.isRestoring置为 true监听器里看到这个标记就直接跳过直到恢复完成后才重新保存最终状态。4. 真实项目里踩过的坑恢复逻辑比想象中更容易翻车4.1 tabBar 页面不能 navigateTo也不能带参路由栈里最特殊的页面就是 tabBar 页面。在 UniApp 里tabBar 页面的跳转只能走uni.switchTabnavigateTo直接跳不过去reLaunch虽然能跳但行为比较特殊。如果深链路的中间某层正好是一个 tabBar 页面重建流程就尴尬了navigateTo跳到 tabBar 页面会失败恢复流程中断。更要命的是uni.switchTab不允许携带参数即使你强行在 URL 后面拼上?idxxxH5 端也会直接忽略。也就是说如果业务里依赖 tabBar 页面的 query 参数这套方案天然不合适。我在项目里的处理办法是保存快照前先判断栈里的页面里有没有 tabBar 页。如果有把 tabBar 页作为栈底处理后面的页面继续用navigateTo重建如果 tabBar 页出现在栈中间就不恢复整条链路只恢复最后一个页面并在控制台打一条警告日志提醒业务方调整页面结构。判断 tabBar 页面的方式// 通过 pages.json 里的 tabBar.list 生成一个路径集合 import pagesJson from /pages.json const tabBarRoutes new Set( (pagesJson.tabBar?.list || []).map(item item.pagePath) ) export function isTabBarPage(route) { const normalized route.replace(/^\//, ) return tabBarRoutes.has(normalized) }4.2 参数里出现对象、特殊字符快照直接丢数据getCurrentPages()拿到的page.options在 UniApp 里一般是字符串键值对。但有两种情况会让你防不胜防。第一种是参数值本身需要二次编码。比如详情页的 id 是一个 URL 编码过的长字符串跳转时直接拼在 URL 里到了page.options里可能就变成了解码后的状态。如果你在恢复时再用encodeURIComponent拼一次参数就重复编码了后端解析出来就是乱码。第二种是跳转时传了对象参数。有些同事会写成uni.navigateTo({ url: /pages/detail?id JSON.stringify(obj) })跳转确实能成功但 JSON.stringify 之后的字符串里会带{、}、这类特殊字符URL 传参时被浏览器自动转义等从这个页面再往下一个页面跳时page.options拿到的值可能已经被截断或者变形。对这种问题我的建议是在保存快照时不要迷信 page.options优先使用页面实例的$page.fullPath重新解析一次参数。这样虽然多了一步解析但能拿到相对干净的原始参数。function getPageParams(page) { const fullPath page.$page?.fullPath || const queryString fullPath.split(?)[1] if (!queryString) return page.options || {} const params {} queryString.split().forEach(pair { const [key, value] pair.split() if (key) params[decodeURIComponent(key)] decodeURIComponent(value || ) }) return params }4.3 登录守卫把恢复流程踢成了死循环这是我在实际项目里踩过最狠的一个坑。项目有全局登录拦截所有进入业务页面的请求如果检测到未登录统一reLaunch到登录页。场景是这样的用户已经登录并浏览了三个页面刷新时服务端 session 过期了。恢复流程启动第一跳reLaunch到栈底页面路由守卫发现未登录马上又reLaunch到登录页。登录页加载完tryRestoreRouteStack再次触发又尝试恢复……用户看到的画面就是页面闪来闪去根本停不下来。解决办法是在恢复前加一道前置校验只有确认登录态有效后才允许恢复恢复期间的跳转要在全局守卫里放行避免被拦截逻辑再次踢回。// 恢复前判断 tryRestoreRouteStack() { if (!this.checkLoginValid()) { // 登录态失效直接清空路由栈回到默认首页 clearRouteStack() return } // ... }同时在全局路由守卫里加一个条件if (app.globalData.isRestoringRouteStack) return next()这行判断要放在登录校验的前面。简单说就是恢复流程是一个“半信任”过程先把栈重建完再让用户走登录校验。这个坑也引出一个更本质的经验路由栈持久化不是万能的它只应该在会话有效期内兜底恢复。一旦登录态、用户身份这类全局条件变了旧的路由栈就没有恢复的意义必须无条件清空。4.4 新版本上线后旧快照里的路由已经不存在前端发版是另一个容易被忽视的问题。用户在一个 H5 页面里浏览路由栈快照里存的是旧版本的pages/activity/detail。第二天我发了个新版把pages/activity/detail改名成了pages/activity/detail-v2或者说整个活动页活动结束了直接下架删掉了。用户第二天打开这个 H5刷新后恢复流程按旧快照里的 route 跳转直接跳到空白页。处理思路和版本号是一个套路在快照的数据模型里加上一个应用版本号字段每次发版如果有路由变化就更新版本号恢复前先比对版本号不一致就直接清空栈。const STORAGE_KEY UNI_H5_ROUTE_STACK_V1 const APP_VERSION 2.3.0 const STORAGE_DATA { version: APP_VERSION, stack: [] } export function getRouteStack() { const data sessionStorage.getItem(STORAGE_KEY) if (!data) return [] try { const parsed JSON.parse(data) if (parsed.version ! APP_VERSION) return [] return parsed.stack || [] } catch (e) { return [] } }更稳妥的做法是在buildPageUrl之前校验 route 是否存在于pages.json的 pages 列表中。不在列表里就直接跳过这一层避免连续跳转几个失效页面导致的连环白屏。5. 进阶从路由栈恢复走向页面现场恢复5.1 把滚动位置和表单草稿一起救回来路由栈恢复解决了“页面链路”的问题但用户感知更强的是“页面内容”还在不在。如果恢复完链路详情页的列表滚动位置回到顶部表单内容清空用户依然会觉得是个坏的体验。页面级状态不建议塞进路由栈快照里那样会让路由栈模块越来越重出问题的概率也高。更合理的做法是在路由栈恢复成功后给每个页面派发一个事件让页面自己决定要恢复哪些状态。// App.vue 恢复完成的回调里 uni.$emit(route-stack-restored, { route: currentItem.route, options: currentItem.options })页面里这样接收onLoad() { uni.$on(route-stack-restored, this.handleRestored) }, onUnload() { uni.$off(route-stack-restored, this.handleRestored) }, methods: { handleRestored(payload) { if (payload.route ! this.route) return // 恢复滚动位置 const savedScroll sessionStorage.getItem(scroll:${this.route}) if (savedScroll) { this.scrollTop Number(savedScroll) } } }这里要做一个约束滚动位置和表单草稿用单独的 sessionStorage key 保存且只在页面onUnload时写入。这样刷新恢复时路由栈只管链路页面只管自己的现场互不干扰职责清晰。5.2 什么时候应该主动清空路由栈路由栈快照不是越持久越好有些业务节点必须主动清空否则会留下脏数据。我总结出三个必须调用clearRouteStack()的场景一是用户完成一次明确的主流程。比如下单支付流程走完页面跳到支付结果页这时候再返回就没有意义。继续保留旧的路由栈只会让用户不断回退到订单确认页、收银台页面造成重复提交的心理压力。二是切换用户身份。用户 A 退出登录换了用户 B 登录之前的路由栈里全是 A 的数据。不清理的话B 用户在刷新后可能会看到 A 用户的订单详情页这就是严重的事故了。三是遇到登录失效。上一节讲的登录守卫踢出场景也必须在踢出时清空快照避免死循环。5.3 微前端与 App 内嵌 H5 场景的额外注意点最后说下两种特殊宿主环境。如果是App 内嵌 H5也就是用 WebView 加载的 HTML 页面sessionStorage 的生命周期可能会被 WebView 原生缓存策略影响。部分安卓客制化 ROM 在 WebView 被销毁重建时sessionStorage 不一定会保留。这种情况下的兜底方案是退一步使用 localStorage但 key 必须带上会话 ID并且配合更积极的清理策略。如果是iframe 页面比如页面被嵌在别人的公众号文章或者第三方系统里sessionStorage 是按 iframe 的源隔离的。只要 iframe 的 src 域名不变sessionStorage 访问不受影响。但要注意iframe 场景下浏览器前进后退行为经常被父页面接管用户点击浏览器返回可能直接退出 iframe根本不会触发页内路由回退。这种情况不要依赖路由栈持久化单独做页面内的“上一步”按钮反而更可靠。还有 UniApp 的 web-view 组件场景。web-view 页面本身是一个原生组件容器它和普通页面的路由栈行为不一样刷新之后 web-view 内部加载的 H5 路由由子页面自己管理和 UniApp 外层页面栈是两层皮。如果你要在里面做路由持久化必须和子页面那边约定好通信协议外层只能保存 web-view 的入口地址内层 H5 自身的路由栈要让内层自管。强行想在外层恢复一个 web-view 内部的深链路几乎是不可能的。我个人在实际项目里的体会是路由栈持久化这件事真正难的不是写出保存和恢复的代码而是搞清楚什么时候该恢复、什么时候该放弃。它本质上是给用户一个“刷新之后还回去”的兜底而不是让开发者把整条页面路径变成 100% 可复现的状态机。先把链路恢复做稳定再逐步加页面现场恢复控制好恢复触发条件和登录态边界这个功能就能跑得很稳。最后分享一个小技巧给 sessionStorage 的 key 加上版本号同时把应用版本号也一起存进去。上线后如果发现旧版本的路由栈导致线上出现白屏不用紧急发版直接在后端配置里加一个标志位让前端的路由栈模块在检测到标志后暴力清空本地快照就行。这个退路关键时候能救命。