企业官网建设流程全解析

先说个我前阵子遇到的场景：一个 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会被映射成路由 push，uni.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

我在设计这套方案的时候，把能想到的存储载体都列了一遍，逐个排除。

最终选择就是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.switchTab，navigateTo直接跳不过去，reLaunch虽然能跳但行为比较特殊。

如果深链路的中间某层正好是一个 tabBar 页面，重建流程就尴尬了：navigateTo跳到 tabBar 页面会失败，恢复流程中断。

更要命的是，uni.switchTab不允许携带参数，即使你强行在 URL 后面拼上?id=xxx，H5 端也会直接忽略。也就是说，如果业务里依赖 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 加上版本号，同时把应用版本号也一起存进去。上线后如果发现旧版本的路由栈导致线上出现白屏，不用紧急发版，直接在后端配置里加一个标志位，让前端的路由栈模块在检测到标志后暴力清空本地快照就行。这个退路，关键时候能救命。