Vue 3 KeepAlive 组件缓存最佳实践airi 桌面伴侣场景下的状态保持、缓存边界与数据新鲜度实战【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi导读KeepAlive是 Vue 3 内置的缓存型组件它不会销毁被切换离开的组件实例而是将实例VNode 与子树状态整体缓存起来从而在动态组件切换、多 Tab 视图或路由跳转时保留用户的操作状态。本指南围绕 airi 仓库内 component-keep-alive.md 的最佳实践规范展开结合仓库中 stage-pocket移动端场景等 Vue 3 应用的真实用法讲清「什么时候该缓存、缓存多大多久、如何保证缓存里的数据不是过期的」。读完你将掌握include/exclude/max三件套的取舍、onActivated/onDeactivated的生命周期协同以及「既想复用缓存又要刷新数据」的 RouterView 缓存方案。适用前提以下内容针对 Vue 3 Composition API script setup项目。airi 仓库在 .agents/skills/vue-best-practices/SKILL.md 中明确将这套实践定义为 Vue 相关开发的标准约定本文是其针对 KeepAlive 的专项深化。一、KeepAlive 的缓存机制与影响等级KeepAlive之所以要单独建立一套最佳实践是因为它的行为与普通组件截然不同默认行为无缓存v-if为假或动态组件切换后组件实例被卸载unmountonUnmounted触发、内部状态ref、DOM 滚动位置、输入框内容等全部丢失。KeepAlive 行为首次渲染后实例被存入内部缓存再次切回时直接从缓存取出复用的 VNode 重新挂载不会重新执行setup因此本地状态被完整保留。文档将 KeepAlive 的影响等级标注为Impact: HIGH——原因是它同时带来三类经典事故缓存视图展示过期数据stale UI、缓存无上限导致内存持续增长memory growth、生命周期行为与直觉不符如onUnmounted不再触发。核心对策归纳为下面六条任务清单仅在「状态保持确实能提升体验」时使用 KeepAlive设置合理的max限制缓存容量为组件显式声明name保证include/exclude匹配可靠用onActivated/onDeactivated编写缓存感知逻辑显式决策缓存的视图何时、如何刷新数据避免缓存内存密集或对安全敏感退出必须清空数据的视图。二、何时使用、何时坚决不用适合缓存切换后状态应当保留的视图典型场景是Tab 切换、多步骤表单、仪表盘——用户在这些视图间来回切换若每次重进都回到初始状态会破坏填了一半的表单、收起的面板或滚动位置。文档给出的对照示例BAD —— 每次切换都重置状态template !-- 切换 Tab 后状态被清空 -- component :iscurrentTab / /templateGOOD —— 状态在切换间保留template !-- 切换 Tab 后状态仍保留 -- KeepAlive component :iscurrentTab / /KeepAlive /template不适合缓存每次进入都应「重新开始」的视图文档明确列出四类禁区每一类都有其内存与正确性依据不适合缓存的场景原因搜索、筛选类页面用户期望看到的是每次进入时的新结果缓存会直接展示上一次的旧查询内存密集组件地图、超大表格、媒体播放器缓存意味着实例连同其底层 WebGL/Canvas/解码资源常驻内存极易触发 OOM 级别的内存膨胀敏感数据流支付、登出、账号切换退出后数据必须被清除缓存会留下「残留会话」构成安全风险后台活动无法暂停的组件轮询、动画、定时器被缓存不代表停止运行若组件自身没有暂停机制资源会被无限占用airi 仓库印证在移动端交互容器 MobileInteractiveArea.vue 中KeepAlive包住的是切换成本很高的聊天历史组件ChatHistory它依赖historyMessages、sending、streaming-message等一串实时状态——这类「重状态、轻内存」的组件正是缓存的最佳候选而 airi 项目中负责渲染 3D/2D 角色的重型舞台画面则刻意不纳入无差别缓存范围只通过白名单精确控制见下文仓库实例。三、限制与控制缓存规模max与include/exclude缓存不是无限保鲜柜。KeepAlive内部按LRU最近最少使用策略维护缓存超过上限后会淘汰最久未被访问的实例。因此始终用max设置容量上限——它直接决定了内存增长的天花板能用include精确到名单就不要用无差别的KeepAlive——把缓存范围收窄到确实需要保留状态的少数视图。template !-- 只缓存最多 5 个实例且仅缓存 Dashboard 与 Settings 两个视图 -- KeepAlive :max5 includeDashboard,Settings component :iscurrentView / /KeepAlive /template注意includeDashboard,Settings是以逗号分隔的字符串形式传入也可传string[]数组或匹配name的正则。超过max后触发 LRU 淘汰被淘汰的实例才真正走卸载流程并触发onUnmounted。airi 仓库印证应用入口 App.vue 在RouterView外层同时使用了v-slot与:include数组白名单RouterView v-slot{ Component } KeepAlive :include[IndexScenePage, StageScenePage] component :isComponent / /KeepAlive /RouterView这里只对两个「场景页」开启缓存保证切换回主场景时画面与交互状态不重建路由树中其余页面则每次进入都会全新挂载——正是「限制缓存范围」原则在路由层的一次落地。其页面路由名如IndexScenePage在 pages/index.vue 顶部通过route langyaml块中的name: IndexScenePage声明与include数组保持严格一致。四、让name与include/exclude精确匹配include/exclude匹配的是组件实例的name选项而不是文件名、也不是路由记录名。最容易踩的坑是组件没有显式name导致白名单永远匹配不上、缓存静默失效。文档给出的规范写法是使用 Vue 3.3 的defineOptions!-- TabA.vue -- script setup defineOptions({ name: TabA }) /scripttemplate !-- 与上面对应的缓存白名单 -- KeepAlive includeTabA,TabB component :iscurrentTab / /KeepAlive /template关键事实script setup组件的name默认不可自动推断历史上依赖文件名推断可靠性与构建工具相关所以要显式声明include/exclude的值是组件名需与defineOptions({ name })完全一致字符串写法区分大小写白名单以外的组件不会被缓存——这既是限制手段也是排查「为什么没缓存上」的第一检查点。五、缓存失效策略Vue 3 中没有「删除单个缓存实例」的 API文档明确了一个容易误用的事实Vue 3 没有直接提供移除某个具体缓存实例的公开 API在 Vue 2 的$destroy时代曾可行Vue 3 中已不可依赖。正确做法是「换 key」或「动态改 include/exclude」来强制重建方案 Akey 版本号bump法——给每个视图维护一个版本计数器缓存中的组件以视图名-版本号作为 key。key改变 ⇒ 旧实例被当作不同组件处理 ⇒ 缓存自然让位给新实例script setup import { ref, reactive } from vue const currentView ref(Dashboard) const viewKeys reactive({ Dashboard: 0, Settings: 0 }) function invalidateCache(view) { viewKeys[view] } /script template KeepAlive component :iscurrentView :key${currentView}-${viewKeys[currentView]} / /KeepAlive /template调用invalidateCache(Settings)后Settings会以Settings-1这个全新 key 重新挂载相当于完成了手动失效。方案 B动态 include/exclude——把失效目标从白名单临时剔除再放回同样能强制其下一次重建。六、缓存组件的生命周期onActivated/onDeactivated被缓存的组件不会在离开时触发onUnmounted这会让依赖卸载钩子做清理的既有代码全部失效。Vue 为此提供一对专门的缓存钩子语义与「进出缓存」精确对应onActivated组件从缓存中重新激活时触发首次挂载也会触发一次onDeactivated组件被移入缓存从视图上隐藏时触发。script setup import { onActivated, onDeactivated } from vue onActivated(() { refreshData() }) onDeactivated(() { pauseTimers() }) /script这两只钩子是 KeepAlive 正确性的命脉激活时刷新数据refreshData()缓存只能保证状态存在不能保证状态新鲜停用时暂停后台活动pauseTimers()被缓存不等于被暂停轮询、动画、订阅必须在这里显式收手避免多个隐藏视图在后台空转。缓存组件内的完整生命周期时间线被 KeepAlive 包裹的组件其钩子执行顺序与普通组件不同每次进出缓存都会经历onDeactivated⇄onActivated的配对而onMounted/onUnmounted只在首次创建与被 LRU 淘汰/真正销毁时各执行一次。从源码结构看airi 各应用统一采用 Composition APIApp.vue 即为script setup langts形态因此在setup顶层直接调用onActivated/onDeactivated即可拿到类型完备的钩子。七、RouterView 缓存与数据新鲜度路由层缓存是 KeepAlive 最常见的落点也是「复用缓存」与「数据新鲜」矛盾最集中的地方。文档给出两种互相补充的策略策略一params 变化时以 key 区分路由默认情况下从/users/1跳到/users/2同一路由组件会被复用同一个缓存实例页面可能停留在上一个用户的旧数据上。按route.fullPath作为 key可让不同参数对应不同缓存实例template router-view v-slot{ Component, route } KeepAlive component :isComponent :keyroute.fullPath / /KeepAlive /router-view /templateairi 的 App.vue 正是这一 v-slot 用法的同构实现——差别在于它使用:include精确圈定缓存范围用路由出口统一承接所有页面切换。router-view v-slot{ Component, route }的解构写法是拿到「当前路由对象」并把它注入:key的标准入口。注意取舍若整个路由树的 path 都参与 key则等价于「每次 URL 变化都换新实例」缓存率会显著下降。实践中应只在params/query 驱动的数据页按 path/query 分段其余静态页面保留固定 key。策略二复用缓存但保持数据新鲜如果希望缓存复用、数据仍是最新文档给出收敛建议在onActivated中刷新并在发起请求前先比较 query/params 是否变化避免无谓重复请求script setup import { onActivated } from vue import { useRoute } from vue-router const route useRoute() let lastLoadedKey onActivated(async () { const currentKey ${route.path}?${route.query.page ?? } if (currentKey lastLoadedKey) return // 参数没变直接展示缓存 lastLoadedKey currentKey await refreshData() }) /script这套「先比较再拉取」的模式是缓存新鲜度的通用解法缓存兜底渲染、激活钩子兜底更新、参数比对兜底防抖三者各司其职即可同时拿到「切换零闪烁」与「数据不过期」。八、airi 中的实战对照与决策清单把上述规范投射回 airi 仓库可以看到决策链条是完整一致的入口路由apps/stage-pocket/src/App.vueRouterViewKeepAliveinclude白名单只缓存IndexScenePage、StageScenePage两个场景页——缓存范围被显式收窄页面命名apps/stage-pocket/src/pages/index.vue主场景页在route langyaml中声明name: IndexScenePage与入口白名单逐字对应——name 与 include 匹配可靠组件层缓存packages/stage-layouts/src/components/Layouts/MobileInteractiveArea.vueKeepAlive包裹ChatHistory其滚动位置与消息发送状态被保留符合「状态保持提升体验」的第一原则——只在重状态、轻内存处缓存。自查清单对应文档 Task List 的落地版该视图切走后用户是否期望状态还在没有则不加缓存缓存容量是否有max上限每个进白名单的组件是否都有显式且唯一的name离开视图时是否通过onDeactivated暂停了轮询/动画/订阅回到视图时是否通过onActivated按需刷新而非无条件信任缓存是否排查过该视图含地图、大表格、媒体等内存密集资源或含退出即须清除的敏感数据相关资源本文规范原文references/component-keep-alive.md技能总入口与 Vue 开发约定.agents/skills/vue-best-practices/SKILL.md路由层 KeepAlive 实例apps/stage-pocket/src/App.vue组件层 KeepAlive 实例packages/stage-layouts/src/components/Layouts/MobileInteractiveArea.vue【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
