前两天被同事拉去排查一个问题，场景非常典型：用户从列表页点进详情，再返回列表，筛选条件全被清空了，页面滚动位置也回到了顶部。同事很委屈地说：“我明明加了 keep-alive，怎么跟没加一样？”

我打开代码一看，App.vue 里的 router-view 确实被 keep-alive 包着，但顺着路由结构往下查，列表页真实渲染的位置在 Layout 内部嵌套的一个 router-view 里，那个 router-view 光秃秃的，一个 keep-alive 都没挂。这就是 Vue3 多级路由缓存失效最常见的场景。

这篇文章把我自己在真实项目中踩过的坑、翻过的源码、上线后验证过的方案全部整理出来，覆盖从 keep-alive 缓存机制到底层匹配规则，再到多级路由场景下的逐层配置、tabs 标签页联动、主动清理缓存，以及缓存命中后页面副作用管理。如果你正在做 Vue3 后台管理系统，或者面试时碰到“多级路由缓存失效”这类题目，这篇值得认真看完。

1. 先从一段真实事故说起：列表页缓存为什么在返回时“消失”了

1.1 现象描述：筛选条件、滚动位置全部丢失

项目背景是 Vue3 + Vue Router 4 + Element Plus，路由结构大概是这样的：

/ -> Layout 组件 /list 列表页 /detail/:id 详情页

App.vue 长这样：

<router-view />

Layout 组件内部维护侧边栏和头部导航，业务页面渲染在 Layout 内部的 router-view 里：

<main> <router-view /> </main>

当时同事在 App.vue 上做了缓存：

<router-view v-slot="{ Component }"> <keep-alive> <component :is="Component" /> </keep-alive> </router-view>

跑起来以后，从列表页进入详情页再返回，列表页筛选条件照丢不误，滚动位置也重置了。他一度以为是 keep-alive 在 Vue3 里有 bug，后来才发现是自己理解偏了。

1.2 第一反应排查：keep-alive 加上去了为什么没用

这个问题我几乎每次带新人都会遇到，核心误区是把 keep-alive 当成“全局缓存开关”来用。

keep-alive 只能缓存它直接渲染的那一个组件，它没有能力穿透路由层级去缓存更深层的内容。你可以把 keep-alive 理解成一间储物柜，router-view 是不同楼层的电梯。你在 1 楼放了一个储物柜，3 楼的物品当然不会自动跑进去，你需要在 3 楼也放一个储物柜才行。

同事的 App.vue 里缓存的是 Layout 组件，Layout 实例确实被缓存住了，但 Layout 内部的列表页组件每次切换子路由时，依然会走销毁、重建的流程，因为它的外层根本没有缓存层。

1.3 真正的原因：keep-alive 缓存的是组件实例，不是路由记录

这是理解整篇文章的关键：keep-alive 的缓存单位是组件实例，不是路由路径。

路由配置只是路径映射关系，真正渲染出来的是一个个组件。多级路由意味着每一层路由都有自己对应的组件实例，我们需要为每一层都独立配置缓存策略。

所谓的“多级路由缓存失效”，本质上不是 keep-alive 失效了，而是 keep-alive 挂在了错误的路由层级上。你缓存了父组件，子组件该重建还是重建。

提示：排查缓存问题时，先问自己一句——我要缓存的组件，到底是哪个 router-view 渲染出来的？这个 router-view 外层有没有 keep-alive？

2. keep-alive 的缓存匹配机制：为什么 include 设置对了还是失效

2.1 缓存 key 从哪来

在 Vue3 的 KeepAlive 源码中，内部维护了一个 cache 对象，用来存放缓存 vnode。默认情况下，缓存 key 取自vnode.key，如果没有显式设置 key，会退回使用vnode.type，也就是组件对象本身。

对于单文件组件来说，vnode.type指向同一个组件对象，所以 key 是稳定的，命中缓存没问题。

但这里藏着一个坑：如果两个不同的路由复用了同一个组件，而且你没有给<component :is>设置 key，这两个路由会共用同一条缓存。

举个例子：

{ path: 'create', component: FormPage, }, { path: 'edit/:id', component: FormPage, }

创建页和编辑页共用 FormPage 组件，如果你在缓存时不做区分，用户先访问创建页，再访问编辑页，看到的可能是创建页留下的表单状态。反之亦然。

解决方式是在渲染时按路由路径区分：

<component :is="Component" :key="route.path" />

route.path每个路由都不一样，这样创建页和编辑页虽然组件相同，也会被当成两个独立缓存条目标识。

2.2 include 匹配的是组件 name，不是路由 name

这是一个非常容易踩的坑。

很多人的写法是这样的：

<keep-alive :include="['user-list']">

include 数组里写的是路由 name，但 keep-alive 的 include/exclude 匹配的是组件内部的 name 字段。如果路由 name 叫user-list，组件内部的 name 是UserListPage，两边对不上，keep-alive 压根不会认为这个组件需要缓存，缓存自然无效。

更坑的是，使用<script setup>时，组件默认不会为一个name字段做显式声明。Vue 在编译 SFC 时确实会根据文件名生成一个__name属性，但这个属性在生产环境打包压缩后不一定可靠，而且它也不是普通options.name那种语义。

所以，实用主义结论是：别依赖文件名推导，显式声明组件的 name。

Vue 3.3 及以上版本可以直接用 defineOptions：

<script setup> defineOptions({ name: 'UserListPage' }) // 业务逻辑 </script>

如果你的项目还在 Vue 3.2 或更早版本，用双 script 块方案：

<script> export default { name: 'UserListPage' } </script> <script setup> // 业务逻辑 </script>

然后在 include 数组里就必须写：

['UserListPage']

2.3 父子层级：内层 RouterView 需要有独立的缓存策略

多级路由场景下，因为外层组件被缓存而导致内层组件状态不同步，这个现象也经常被误判为“缓存失效”。

举个例子，Layout 组件里有侧边栏菜单，菜单的高亮状态依赖当前路由。如果 Layout 被 keep-alive 缓存，切换一级菜单时 Layout 组件本身不会重新创建，created、onMounted这些钩子都不会再执行。虽然响应式依赖会触发部分更新，但如果你在onMounted里做了路由初始化逻辑，这部分代码不会重新跑，侧边栏高亮可能停留在上一次的状态。

这种情况下，你看到的页面表现是“好像缓存没生效，页面状态不对”，但实际上缓存生效了，生效得过头了——不该缓存的 Layout 状态也被缓存了。

另外一个反向场景更隐蔽：外层组件被缓存后，内层 RouterView 的子路由切换依然会发生，这时候内层 keep-alive 是否配置，直接决定子页面是否被缓存。如果内层没有配置 keep-alive，子页面每次切换都会重建。

所以，多级路由缓存失效的根因，除了 include 匹配不上，最常见的就是内层 RouterView 根本没有自己的 keep-alive。

2.4 include 变化的过期清理机制

Vue3 的 KeepAlive 组件会监听 include 数组的变化，一旦数组内容更新，内部会执行pruneCache，把不在白名单里的缓存 vnode 清理掉。

这个机制非常重要，它是后面实现“主动清除缓存”功能的理论基础。

当你从 include 数组里移除一个组件名时，KeepAlive 会把这个组件对应的缓存清掉，并调用该组件实例的deactivated钩子；下次再进入这个组件时，它不再命中缓存，会重新走created、mounted流程。如果你在移出缓存后的下一个 tick 又把组件名加回 include，那么组件重新创建后，依然会进入缓存体系。

掌握了这个机制，你就能精确控制某个页面何时该被缓存、何时该被重置。

3. 多级路由缓存的实战配置方案：从 Layout 到页面的逐层处理

3.1 推荐结构：App 不缓存 Layout，Layout 缓存页面

我见过不少项目上来就在 App.vue 上包 keep-alive，想实现“全局页面都缓存”，结果经常踩坑。更推荐的架构是：App.vue 里保持简单的 router-view，不包 keep-alive；在 Layout 内部对真正承载业务页面的 router-view 做缓存。

这样做有几点理由：

• Layout 承担侧边栏、顶栏、面包屑等框架性状态，这些状态依赖当前路由，重建更合理。
• 真正需要缓存的是列表页、表单页这些包含用户操作数据的业务组件。
• 职责分离后，后续维护和问题定位会轻松很多。

3.2 RouterView 的 v-slot 标准写法

在 Vue3 + Vue Router 4 中，推荐使用 v-slot 来获取组件和路由信息，这样才能实现动态缓存控制。

Layout 内部的写法：

<router-view v-slot="{ Component, route }"> <keep-alive :include="cachedViews"> <component :is="Component" :key="route.path" /> </keep-alive> </router-view>

route.path作为 key 的唯一性最可靠。有些项目喜欢用route.name，但同一个组件被多个路由复用时，这个方案会出问题。用route.path最稳。

这里还可以做一个性能优化：如果有些页面明确不需要缓存，可以用 include 白名单来控制，白名单之外的路由面板会自动重建，不影响缓存队列。

3.3 路由 meta 与 include 白名单管理

动态维护缓存白名单，推荐用一个全局状态来管理。我在项目里用 Pinia 实现了一个appStore：

// stores/app.js import { defineStore } from 'pinia' export const useAppStore = defineStore('app', () => { const cachedViews = ref([]) function addCachedView(name) { if (name && !cachedViews.value.includes(name)) { cachedViews.value.push(name) } } function removeCachedView(name) { cachedViews.value = cachedViews.value.filter((item) => item !== name) } function clearCachedView() { cachedViews.value = [] } return { cachedViews, addCachedView, removeCachedView, clearCachedView } })

在路由配置的 meta 里做约定：

{ path: 'list', component: UserListPage, meta: { keepAlive: true, cacheName: 'UserListPage' } }

通过全局后置钩子维护 include：

router.afterEach((to) => { if (to.meta.keepAlive && to.meta.cacheName) { appStore.addCachedView(to.meta.cacheName) } })

这里我把cacheName单独拎出来配置，而不是直接用to.name，就是为了避免路由 name 和组件 name 混为一谈。两个地方独立配置，维护起来反而更清晰。

3.4 多级嵌套的两种处理思路

如果你的项目确实存在 Layout 嵌套 Layout 的情况，这里有两种处理思路。

第一种：每一层 RouterView 都配置同样的缓存逻辑，每层独立管理缓存。这种方案适合 UI 结构确实需要多层嵌套、且每一层都有独立状态需要保持的场景。缺点是配置代码重复，排查链路变长。

第二种：先把路由规划好，把需要缓存的页面尽量“拍平”到同一层。很多后台管理系统最终都会走向这种架构——菜单层级做深，但路由只保留 Layout 一层嵌套。这样缓存配置统一，后期维护成本最低。

我在实际项目中更推荐第二种，尤其当页面数量多、权限逻辑复杂时，拍平后的路由结构能省掉大量身心俱疲的调试时间。

4. 高级场景：tabs 标签页、动态缓存与主动清理

4.1 联动 tabs 标签页维护缓存列表

后台管理系统经常用 tabs 标签页管理多页面，用户打开一个新页面就新增一个 tab，关掉 tab 就关闭对应页面。

这时候缓存列表必须和 tabs 联动。用户关闭标签页时，不仅要把页面 remove 掉，还要把对应页面的缓存从 include 白名单里移除。

关闭 tab 的处理函数大致是这样：

function handleCloseTag(tag) { // 先移除缓存 appStore.removeCachedView(tag.cacheName) // 再关闭标签 tagsStore.removeTag(tag) // 如果关闭的是当前页，需要跳转到其他页面 if (tag.path === route.path) { router.push(tagsStore.getLatestTag().path) } }

注意，移除缓存后 KeepAlive 内部的pruneCache会自动生效，不需要手动去“销毁组件”。这一步如果你不处理，就会出现页面已经关了，但组件缓存还躺在内存里，下次进入时数据还是旧的。

4.2 主动清除单个组件缓存

“刷新当前页”是后台系统很常见的需求，用 KeepAlive 的 include 动态变更来实现，比window.location.reload()优雅得多。

async function refreshPage() { const { cacheName } = route.meta if (!cacheName) return appStore.removeCachedView(cacheName) await nextTick() appStore.addCachedView(cacheName) }

这段代码的逻辑是先把组件名从缓存白名单里移除，让 KeepAlive 触发pruneCache把对应缓存清掉；nextTick后再把组件名加回白名单，下一次进入这个页面时，组件重新创建，创建完成后继续进入缓存体系。

整个过程不会影响其他页面的缓存状态，比用v-if强制重建整个 RouterView 要精准得多。

注意：refreshPage执行后，当前页面组件会立即被卸载并重新创建，所以页面可能有短暂的重载闪烁。这是正常现象，体验上可以接受。

4.3 max 限制与 LRU 淘汰造成的“假性缓存失效”

Vue3 的 KeepAlive 支持max属性，比如<keep-alive :max="10">，当缓存超过 10 个组件时，会采用 LRU 策略淘汰最久未使用的缓存。

这个坑非常隐蔽。

假设项目里有 20 个页面需要缓存，max设置成 10，用户从页面 1 依次访问到页面 15，此时页面 1 到页面 5 的缓存已经被 LRU 淘汰掉了。用户如果点击浏览器返回，页面 4 虽然还在 include 白名单里，但实际缓存已经不存在，组件会重新创建。用户感知就是“缓存失效了”，但 root cause 其实是 LRU 淘汰策略在工作。

处理方式有两个方向：

• 如果记忆体积可控，不要随意给 KeepAlive 加过小的 max。
• 如果页面数量确实很多，就要从架构层面考虑，哪些页面必须缓存、哪些可以不缓存，而不是所有页面一把梭。

我见过一个项目把所有页面都塞进 include，结果内存占用长期居高不下，最后通过分析访问路径，只缓存高频列表页，才把性能问题解决掉。

5. 页面组件内部的副作用管理：缓存后 onMounted 只执行一次怎么办

5.1 生命周期变化

组件被 KeepAlive 缓存后，生命周期行为会发生明显变化，这是很多业务代码出现 bug 的根源。

普通组件只有 mounted / unmounted 两个主要阶段；被缓存的组件会多出 activated / deactivated 两个阶段：

• 首次进入页面：onMounted和onActivated都会触发。
• 从缓存中切回页面：只触发onActivated。
• 从页面切走：触发onDeactivated。

这就是为什么很多人会发现，列表页从详情页返回后，onMounted里的数据请求不再执行了。因为组件实例还活着，只是被“收起来”了，onMounted只在首次创建时执行一次。

5.2 避免初始重复请求

因为首次进入会同时触发onMounted和onActivated，如果你在这两个钩子里都写了数据请求，页面第一次加载就会请求两次。

常见做法是设置一个标记：

let hasActivated = false onMounted(() => { fetchList() }) onActivated(() => { if (hasActivated) { fetchList() } hasActivated = true })

第一次进入时hasActivated为 false，onActivated里跳过重复请求；当用户从其他页面切回时，hasActivated已经是 true，就会重新拉取数据。

这个标记法我在多个项目里用过，简单可靠。

5.3 定时器、事件监听、图表实例的恢复

组件被缓存后，实例不销毁，很多副作用如果不主动清理，会持续堆积。

最常见的是定时器：

onMounted(() => { timer = setInterval(refreshData, 3000) }) onDeactivated(() => { clearInterval(timer) }) onUnmounted(() => { clearInterval(timer) })

注意，onDeactivated才是缓存组件的“离开”生命周期，onUnmounted只有在组件真正销毁时才会触发。如果只在onUnmounted里清理定时器，用户切到详情页后，定时器依然在跑，数据还在背后偷偷刷新。

事件监听、ECharts 实例、WebSocket 连接等也是同理。ECharts 图表实例在组件被缓存后，容器还在，但可能需要重新 resize 或刷新数据。一个经验是统一在onActivated里检查图表实例的状态，必要时调用resize()重新绘制。

6. 排查与验证：缓存失效问题的定位思路

6.1 先确认组件 name 是否符合预期

排查缓存问题时，第一件事不是翻代码，而是确认组件 name 到底叫什么。

最简单的方法是在组件里临时加一个日志：

onMounted(() => { console.log('当前组件 name:', (getCurrentInstance()).type.name) })

控制台输出的 name，必须和 include 数组里的值完全一致，多一个空格、大小写不同，都会匹配失败。

6.2 判断当前 RouterView 是否真的被 keep-alive 包裹

这个判断也很容易，在组件里同时打点onMounted和onActivated：

onMounted(() => console.log('mounted')) onActivated(() => console.log('activated'))

如果每次进入页面都输出mounted，说明缓存没有命中，组件每次都在重建。如果只有第一次输出mounted，后续进入只输出activated，说明缓存已经生效。

这个方法是排查“缓存失效”最快的二分定位法，能迅速区分是缓存没配置，还是 include 匹配失败。

6.3 在 DevTools 中检查组件缓存状态

Vue DevTools 的组件树中可以看到 KeepAlive 组件内部状态，包括 cache 和 keys。如果 include 数组值正确，但 cache 中没有对应组件，说明缓存曾在某个时间点被清除。常见原因有三个：

• 动态 include 数组里曾经移除过这个组件名。
• KeepAlive 设置了 max，被 LRU 策略淘汰了。
• 渲染时 key 不稳定，导致每次生成的缓存 key 都不一样。

把这三个原因逐个排查完，90% 的“缓存失效”问题都能定位到具体环节。

最后分享一句我总结的口诀：keep-alive 缓存的是组件实例，不是路由路径；include 匹配的是组件 name，不是路由 name；多级路由下，每一层 RouterView 都要问自己——这里到底该不该缓存。把这三句话想清楚，Vue3 多级路由缓存就不会再让你半夜起来改代码了。