Vue 3 KeepAlive元件快取實戰：路由級快取與記憶體優化的5個核心策略

元件快取痛點：為什麼KeepAlive如此難用

2026年，Vue 3的<KeepAlive>仍是前端路由快取的首選方案，但路由切換狀態遺失、記憶體洩漏、include/exclude配置混亂、快取資料不更新這四大痛點讓無數開發者踩坑。KeepAlive的設計初衷是快取元件實例避免重複渲染，但在生產環境中，快取管理遠比想像中複雜。

痛點	具體表現	影響
路由切換狀態遺失	從列表頁進入詳情頁再返回，捲動位置和篩選條件被重置	使用者體驗極差
KeepAlive記憶體洩漏	快取元件未正確銷毀，閉包引用無法釋放	頁面越來越卡
include/exclude配置混亂	動態路由下元件名稱匹配失效，快取名單難以維護	快取形同虛設
快取元件資料不更新	快取元件複用舊資料，介面回傳新資料無法反映	資料不一致

核心觀點：KeepAlive不是簡單的<router-view>包裹，而是需要從路由meta宣告、動態快取名單管理、LRU淘汰策略、資料重新整理機制到記憶體洩漏防護的全鏈路工程化方案。

---

核心概念速覽

概念	說明
KeepAlive	Vue 3內建元件，快取動態元件實例而非銷毀重建
include/exclude	按元件名稱匹配，控制哪些元件需要/不需要快取
max	最大快取實例數，超出時按LRU策略淘汰最久未存取的實例
activated/deactivated	快取元件啟用/停用時的生命週期鉤子
路由meta	路由配置中的自訂欄位，宣告該路由是否需要快取
快取Key	KeepAlive內部用於識別快取實例的唯一鍵，預設為元件name
元件實例	被KeepAlive快取的VNode及關聯的響應式狀態和DOM
記憶體管理	監控和清理快取元件佔用的記憶體，防止洩漏

---

5大挑戰深度分析

挑戰1：快取元件記憶體洩漏

被KeepAlive快取的元件持有大量閉包引用：響應式資料、事件監聽器、計時器、DOM引用。當路由頻繁切換時，快取實例不斷累積，記憶體佔用持續增長。在低階裝置上，10個快取元件就可能佔用超過50MB記憶體。

挑戰2：路由級快取控制

不同路由對快取的需求不同：列表頁需要快取捲動位置和篩選狀態，詳情頁通常不需要快取。如何透過路由meta宣告式控制快取行為，而非硬編碼include名單？

挑戰3：快取資料過期

快取元件的activated鉤子觸發時，資料可能已經過期（如列表頁資料在背景已更新）。如何在啟用時智慧重新整理資料，同時保留使用者互動狀態？

挑戰4：動態include管理

動態路由、權限路由導致元件名稱在執行時才能確定。靜態的include配置無法覆蓋所有場景，需要執行時動態管理快取名單。

挑戰5：快取Key衝突

同名元件在不同路由下可能需要獨立快取（如多個分頁使用同一個列表元件）。預設的元件name作為快取Key會導致衝突，需要自訂快取Key策略。

---

策略1：基礎KeepAlive與路由meta配置

// src/router/index.ts
import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router'

interface RouteMeta {
  keepAlive?: boolean
  cacheKey?: string
}

const routes: RouteRecordRaw[] = [
  {
    path: '/users',
    name: 'UserList',
    component: () => import('@/views/UserList.vue'),
    meta: { keepAlive: true, cacheKey: 'UserList' } as RouteMeta
  },
  {
    path: '/users/:id',
    name: 'UserDetail',
    component: () => import('@/views/UserDetail.vue'),
    meta: { keepAlive: false } as RouteMeta
  },
  {
    path: '/settings',
    name: 'Settings',
    component: () => import('@/views/Settings.vue'),
    meta: { keepAlive: true, cacheKey: 'Settings' } as RouteMeta
  }
]

const router = createRouter({
  history: createWebHistory(),
  routes
})

export default router

// src/App.vue
import { computed, type Component } from 'vue'
import { useRouter } from 'vue-router'
import Layout from '@/layouts/Layout.vue'

const router = useRouter()

const cacheComponents = computed<string[]>(() => {
  return router.getRoutes()
    .filter(route => route.meta.keepAlive)
    .map(route => (route.meta.cacheKey as string) || route.name as string)
})

<!-- src/App.vue template -->
<template>
  <Layout>
    <RouterView v-slot="{ Component, route }">
      <KeepAlive :include="cacheComponents">
        <component :is="Component" :key="route.meta.cacheKey || route.name" />
      </KeepAlive>
    </RouterView>
  </Layout>
</template>

關鍵要點：透過路由meta宣告keepAlive控制快取行為，cacheKey解決同名元件衝突。<RouterView>的v-slot取得當前元件實例，:key確保快取Key唯一。

---

策略2：動態include/exclude管理

// src/composables/useKeepAliveStore.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const useKeepAliveStore = defineStore('keepAlive', () => {
  const includeList = ref<Set<string>>(new Set())
  const excludeList = ref<Set<string>>(new Set())

  const includeArray = computed(() => Array.from(includeList.value))
  const excludeArray = computed(() => Array.from(excludeList.value))

  function addInclude(name: string): void {
    includeList.value.add(name)
    excludeList.value.delete(name)
  }

  function removeInclude(name: string): void {
    includeList.value.delete(name)
  }

  function addExclude(name: string): void {
    excludeList.value.add(name)
    includeList.value.delete(name)
  }

  function removeExclude(name: string): void {
    excludeList.value.delete(name)
  }

  function clearCache(name: string): void {
    removeInclude(name)
    includeList.value.add(name)
  }

  function resetAll(): void {
    includeList.value.clear()
    excludeList.value.clear()
  }

  return {
    includeList,
    excludeList,
    includeArray,
    excludeArray,
    addInclude,
    removeInclude,
    addExclude,
    removeExclude,
    clearCache,
    resetAll
  }
})

// src/composables/useRouteKeepAlive.ts
import { watch } from 'vue'
import { useRoute } from 'vue-router'
import { useKeepAliveStore } from './useKeepAliveStore'

export function useRouteKeepAlive(): void {
  const route = useRoute()
  const keepAliveStore = useKeepAliveStore()

  watch(
    () => route.name,
    (newName, oldName) => {
      if (oldName && route.matched.some(r => r.meta.keepAlive)) {
        const oldRoute = route.matched.find(r => r.name === oldName)
        if (oldRoute?.meta.keepAlive) {
          keepAliveStore.addInclude(oldRoute.meta.cacheKey as string || oldName as string)
        }
      }

      if (newName) {
        const newRoute = route.matched.find(r => r.name === newName)
        if (newRoute?.meta.keepAlive === false) {
          keepAliveStore.addExclude(newName as string)
        }
      }
    },
    { immediate: true }
  )
}

<!-- 動態KeepAlive包裹 -->
<template>
  <RouterView v-slot="{ Component, route }">
    <KeepAlive :include="keepAliveStore.includeArray" :exclude="keepAliveStore.excludeArray">
      <component :is="Component" :key="route.meta.cacheKey || route.name" />
    </KeepAlive>
  </RouterView>
</template>

<script setup lang="ts">
import { useKeepAliveStore } from '@/composables/useKeepAliveStore'
import { useRouteKeepAlive } from '@/composables/useRouteKeepAlive'

const keepAliveStore = useKeepAliveStore()
useRouteKeepAlive()
</script>

---

策略3：max快取上限與LRU淘汰

// src/composables/useKeepAliveLru.ts
import { ref, watch, onUnmounted, type Ref } from 'vue'
import { useRoute } from 'vue-router'

interface CacheEntry {
  name: string
  lastAccessed: number
  memoryEstimate: number
}

export function useKeepAliveLru(maxCache: number = 10) {
  const route = useRoute()
  const keepAliveStore = useKeepAliveStore()
  const cacheEntries = ref<CacheEntry[]>([])
  const currentCacheSize = ref(0)

  function touchEntry(name: string): void {
    const existing = cacheEntries.value.find(e => e.name === name)
    if (existing) {
      existing.lastAccessed = Date.now()
    } else {
      cacheEntries.value.push({
        name,
        lastAccessed: Date.now(),
        memoryEstimate: 0
      })
    }
  }

  function evictOldest(): string | null {
    if (cacheEntries.value.length === 0) return null
    const sorted = [...cacheEntries.value].sort((a, b) => a.lastAccessed - b.lastAccessed)
    const oldest = sorted[0]
    cacheEntries.value = cacheEntries.value.filter(e => e.name !== oldest.name)
    keepAliveStore.removeInclude(oldest.name)
    return oldest.name
  }

  function enforceLimit(): void {
    while (cacheEntries.value.length >= maxCache) {
      evictOldest()
    }
  }

  watch(
    () => route.name,
    (name) => {
      if (!name) return
      const routeConfig = route.matched.find(r => r.name === name)
      if (!routeConfig?.meta.keepAlive) return

      const cacheKey = (routeConfig.meta.cacheKey as string) || (name as string)
      touchEntry(cacheKey)
      keepAliveStore.addInclude(cacheKey)
      enforceLimit()
      currentCacheSize.value = cacheEntries.value.length
    }
  )

  function getCacheStats(): { size: number; max: number; entries: CacheEntry[] } {
    return {
      size: cacheEntries.value.length,
      max: maxCache,
      entries: [...cacheEntries.value]
    }
  }

  function clearAll(): void {
    cacheEntries.value.forEach(e => keepAliveStore.removeInclude(e.name))
    cacheEntries.value = []
    currentCacheSize.value = 0
  }

  onUnmounted(() => clearAll())

  return {
    cacheEntries,
    currentCacheSize,
    getCacheStats,
    clearAll,
    evictOldest
  }
}

LRU淘汰原理：KeepAlive內建的max屬性已實作LRU淘汰，但無法感知路由語意。自訂LRU策略可以在淘汰前執行清理邏輯（如清除元件內的計時器、取消網路請求），避免「殭屍快取」。

---

策略4：快取元件資料重新整理策略

// src/composables/useCacheRefresh.ts
import { onActivated, ref, type Ref } from 'vue'

interface RefreshOptions {
  staleTime?: number
  refreshOnActivate?: boolean
  preserveScroll?: boolean
}

export function useCacheRefresh<T>(
  fetchFn: () => Promise<T>,
  options: RefreshOptions = {}
) {
  const {
    staleTime = 5 * 60 * 1000,
    refreshOnActivate = true,
    preserveScroll = true
  } = options

  const data: Ref<T | null> = ref(null)
  const loading = ref(false)
  const lastFetchedAt = ref(0)
  const scrollPosition = ref({ x: 0, y: 0 })

  async function fetchData(forceRefresh = false): Promise<void> {
    const isStale = Date.now() - lastFetchedAt.value > staleTime
    if (!forceRefresh && !isStale && data.value !== null) return

    loading.value = true
    try {
      data.value = await fetchFn()
      lastFetchedAt.value = Date.now()
    } finally {
      loading.value = false
    }
  }

  function saveScrollPosition(): void {
    if (preserveScroll) {
      scrollPosition.value = {
        x: window.scrollX,
        y: window.scrollY
      }
    }
  }

  function restoreScrollPosition(): void {
    if (preserveScroll) {
      window.scrollTo(scrollPosition.value.x, scrollPosition.value.y)
    }
  }

  onActivated(() => {
    if (refreshOnActivate) {
      fetchData()
    }
    restoreScrollPosition()
  })

  return {
    data,
    loading,
    lastFetchedAt,
    scrollPosition,
    fetchData,
    saveScrollPosition,
    restoreScrollPosition
  }
}

// 在快取元件中使用
// src/views/UserList.vue
import { useCacheRefresh } from '@/composables/useCacheRefresh'
import { fetchUserList } from '@/api/user'

const { data: users, loading, fetchData, saveScrollPosition } = useCacheRefresh(
  () => fetchUserList({ page: 1, size: 20 }),
  { staleTime: 3 * 60 * 1000, preserveScroll: true }
)

import { onBeforeRouteLeave } from 'vue-router'
onBeforeRouteLeave(() => {
  saveScrollPosition()
})

---

策略5：記憶體洩漏偵測與修復

// src/composables/useKeepAliveMonitor.ts
import { onMounted, onUnmounted, ref } from 'vue'

interface MemorySnapshot {
  timestamp: number
  usedJSHeapSize: number
  totalJSHeapSize: number
  cacheCount: number
}

export function useKeepAliveMonitor(intervalMs: number = 10000) {
  const snapshots = ref<MemorySnapshot[]>([])
  const isLeaking = ref(false)
  let timer: ReturnType<typeof setInterval> | null = null

  function takeSnapshot(): MemorySnapshot | null {
    const performance = window.performance as any
    if (!performance?.memory) return null

    const keepAliveStore = useKeepAliveStore()
    return {
      timestamp: Date.now(),
      usedJSHeapSize: performance.memory.usedJSHeapSize,
      totalJSHeapSize: performance.memory.totalJSHeapSize,
      cacheCount: keepAliveStore.includeArray.length
    }
  }

  function detectLeak(): void {
    if (snapshots.value.length < 3) return
    const recent = snapshots.value.slice(-5)
    const heapGrowth = recent[recent.length - 1].usedJSHeapSize - recent[0].usedJSHeapSize
    const avgGrowthRate = heapGrowth / recent.length
    isLeaking.value = avgGrowthRate > 1024 * 1024
  }

  onMounted(() => {
    timer = setInterval(() => {
      const snapshot = takeSnapshot()
      if (snapshot) {
        snapshots.value.push(snapshot)
        if (snapshots.value.length > 50) {
          snapshots.value = snapshots.value.slice(-30)
        }
        detectLeak()
      }
    }, intervalMs)
  })

  onUnmounted(() => {
    if (timer) clearInterval(timer)
  })

  return { snapshots, isLeaking, takeSnapshot }
}

// 快取元件洩漏修復模式
// src/composables/useSafeCacheComponent.ts
import { onDeactivated, onUnmounted } from 'vue'

export function useSafeCacheComponent() {
  const timers: ReturnType<typeof setTimeout>[] = []
  const intervals: ReturnType<typeof setInterval>[] = []
  const eventListeners: Array<{ target: EventTarget; event: string; handler: EventListener }> = []

  function safeSetTimeout(fn: () => void, ms: number): ReturnType<typeof setTimeout> {
    const id = setTimeout(fn, ms)
    timers.push(id)
    return id
  }

  function safeSetInterval(fn: () => void, ms: number): ReturnType<typeof setInterval> {
    const id = setInterval(fn, ms)
    intervals.push(id)
    return id
  }

  function safeAddEventListener(
    target: EventTarget,
    event: string,
    handler: EventListener
  ): void {
    target.addEventListener(event, handler)
    eventListeners.push({ target, event, handler })
  }

  function cleanup(): void {
    timers.forEach(id => clearTimeout(id))
    intervals.forEach(id => clearInterval(id))
    eventListeners.forEach(({ target, event, handler }) => {
      target.removeEventListener(event, handler)
    })
    timers.length = 0
    intervals.length = 0
    eventListeners.length = 0
  }

  onDeactivated(() => cleanup())
  onUnmounted(() => cleanup())

  return { safeSetTimeout, safeSetInterval, safeAddEventListener, cleanup }
}

---

避坑指南

場景	錯誤做法	正確做法
快取Key	❌ 使用預設元件name，多路由複用同一元件時衝突	✅ 透過路由meta.cacheKey自訂唯一快取識別
資料重新整理	❌ 在activated中無條件重新請求，遺失使用者操作狀態	✅ 使用staleTime策略，僅在資料過期時重新整理
記憶體清理	❌ 只在onUnmounted中清理計時器和事件監聽	✅ 同時在onDeactivated中清理，避免快取期間洩漏
include管理	❌ 硬編碼include字串陣列，無法動態增刪	✅ 使用Pinia store動態管理，路由切換時自動更新
max配置	❌ 設定過大的max值或不設定，快取無限增長	✅ 根據裝置記憶體設定合理上限（建議5-15），配合LRU淘汰

---

報錯排查

錯誤訊息	原因	解決方案
Component is not cached	include/exclude匹配的元件名與元件實際name不一致	確認元件defineComponent({ name: 'xxx' })與include值一致
Maximum call stack exceeded	KeepAlive巢狀使用或循環依賴	避免KeepAlive巢狀，檢查路由配置是否有循環引用
activated hook not firing	元件未被KeepAlive包裹或include未匹配	檢查路由meta.keepAlive和include名單是否包含該元件
Cache key collision	不同路由使用同名元件，快取Key衝突	使用route.meta.cacheKey區分不同路由的快取實例
Memory usage keeps growing	快取元件中存在未清理的閉包引用	在onDeactivated中清理計時器、事件監聽、AbortController
Stale data after navigation	快取元件activated時未重新整理過期資料	實作staleTime機制，activated時檢查資料新鮮度
include regex not matching	include使用正規表示式但元件名不匹配	確保正規表示式與元件name完全匹配，注意大小寫
KeepAlive max not working	max屬性值設定過大或元件未正確註冊name	設定合理的max值（5-15），確保元件有name屬性
Scroll position lost	快取元件重新啟用時捲動位置被重置	在onDeactivated儲存scrollY，onActivated中恢復
Vuex/Pinia state out of sync	快取元件的本地狀態與store狀態不一致	activated時從store同步最新狀態，或使用storeToRefs保持響應式

---

進階優化技巧

1. 按裝置記憶體自適應快取上限

import { computed } from 'vue'

function getAdaptiveMaxCache(): number {
  const navigator = window.navigator as any
  const deviceMemory = navigator.deviceMemory || 4
  if (deviceMemory <= 2) return 3
  if (deviceMemory <= 4) return 5
  if (deviceMemory <= 8) return 10
  return 15
}

2. 快取預熱與預載入

import { onMounted } from 'vue'

function useCachePreload(routeNames: string[]): void {
  onMounted(() => {
    const router = useRouter()
    routeNames.forEach(name => {
      const route = router.resolve({ name })
      const component = route.matched[0]?.components?.default
      if (typeof component === 'function') {
        (component as () => Promise<any>)()
      }
    })
  })
}

3. 快取元件效能標記

import { onActivated, onDeactivated } from 'vue'

function useCachePerformanceMark(name: string): void {
  onActivated(() => {
    performance.mark(`${name}-activated-start`)
    requestAnimationFrame(() => {
      performance.mark(`${name}-activated-end`)
      performance.measure(`${name}-activated`, `${name}-activated-start`, `${name}-activated-end`)
    })
  })

  onDeactivated(() => {
    performance.mark(`${name}-deactivated`)
  })
}

4. 快取快照與恢復

import { onDeactivated, onActivated, ref } from 'vue'

function useCacheSnapshot<T extends Record<string, any>>(initialState: T) {
  const snapshot = ref<T | null>(null)

  onDeactivated(() => {
    snapshot.value = { ...initialState }
  })

  onActivated(() => {
    if (snapshot.value) {
      Object.assign(initialState, snapshot.value)
    }
  })

  return { snapshot }
}

---

對比分析

維度	KeepAlive	手動狀態管理	Pinia持久化	sessionStorage
快取粒度	元件實例級	手動選擇欄位	Store欄位級	字串鍵值對
DOM保留	保留完整DOM	不保留	不保留	不保留
生命週期	activated/deactivated	手動管理	store action	手動讀寫
記憶體佔用	高（含DOM+響應式）	低	低	極低
資料型別	任意（含函式引用）	任意	可序列化值	僅字串
跨頁面	僅路由級	可跨路由	全域共享	同源頁面共享
重新整理保留	是（記憶體中）	否	是（持久化）	是
適用場景	表單/列表狀態保留	精細欄位快取	全域狀態持久化	簡單資料暫存

---

總結展望

KeepAlive元件快取不是簡單的開關配置，而是從路由宣告、動態名單管理、LRU淘汰、資料重新整理到記憶體洩漏防護的全鏈路工程。5個核心策略——路由meta宣告式快取、動態include/exclude管理、max上限與LRU淘汰、staleTime資料重新整理、記憶體洩漏偵測修復——構成了生產級KeepAlive方案的完整閉環。

2026年，隨著Vue Vapor Mode的推進，KeepAlive的快取機制可能從VNode級轉向DOM級，但快取管理的工程化思路不會改變。建議從路由meta宣告開始，逐步引入動態管理和記憶體監控，最終形成適合自身業務的快取策略。

---

線上工具推薦

• Vue SFC Playground — 線上測試KeepAlive元件行為和生命週期
• Chrome DevTools Memory — 分析快取元件記憶體佔用和洩漏
• Vue DevTools — 檢視KeepAlive快取實例列表和狀態
• JSON格式化工具 — 格式化路由配置和快取策略JSON
• Hash編碼工具 — 產生快取Key的雜湊值避免衝突