Vue3 动态路由在生产环境才出现白屏的排查与解决（keep-alive 踩坑实录）

摘要

项目基于 Vue3 + Vue Router + 动态路由，在开发环境运行正常，但打包部署后出现路由切换白屏、无报错、刷新会正常加载 的问题。最终定位为 keep-alive 的 include 使用了路由 name，而非组件 name，在生产环境异步组件场景下直接阻断渲染。本文给出问题判断依据、根因分析以及最小改动的稳定解决方案。

一、核心结论（先看）

keep-alive 的 include 只能匹配组件的 name，不能使用路由 name。

错误使用方式在开发环境可能"看起来正常"，但在 生产环境 + 动态路由 + 异步组件 下会直接导致页面白屏。

二、问题表现

场景	结果
本地 dev	正常
build 后部署	路由切换白屏
控制台	无报错
刷新页面	偶发恢复

三、直接原因（代码层面）

❌ 错误逻辑

ts 复制代码

// guards.ts
const currentComName =
  to.matched.find(item => item.name === to.name)?.name;
<keep-alive :include="keepAliveComponents">
  <component :is="Component" />
</keep-alive>

问题点

to.name → 路由 name
keep-alive include → 组件 name
两者永远不可能匹配

四、为什么只在生产环境出问题？

开发环境

同步组件
HMR 强制刷新
keep-alive 行为宽松

生产环境

异步 import
chunk 拆分
组件 name 严格生效
include 匹配失败 → 组件不渲染

五、根本原因总结

复制代码

路由 name ≠ 组件 name
keep-alive 只认组件 name
include 不匹配 → 缓存失败 → 渲染被阻断 → 白屏

六、最终解决方案（稳定优先）

核心策略

彻底移除 keep-alive
使用 route.fullPath 强制重新渲染
保证动态路由在生产环境可控运行

七、关键修改代码

1️⃣ Main / index.vue（最关键）

复制代码

<template>
  <RouterView>
    <template #default="{ Component, route }">
      <div v-if="!Component">
        ❌ 组件加载失败：{{ route.path }}
      </div>

      <component
        v-else
        :is="Component"
        :key="route.fullPath"
      />
    </template>
  </RouterView>
</template>

修改点：

❌ 移除 <keep-alive>
❌ 移除 <transition>
✅ 使用 route.fullPath 作为 key

2️⃣ 路由守卫增加诊断日志（辅助）

复制代码

const matchedRoute = to.matched.at(-1);

console.log('route matched', {
  path: to.path,
  hasComponent: matchedRoute?.components?.default,
});

八、结果对比

项目	修改前	修改后
路由切换	白屏	正常
页面刷新	偶发	稳定
keep-alive	异常	移除
生产可控性	低	高

九、经验结论

keep-alive 是 组件缓存，不是路由缓存
动态路由场景下，误用 include 极易在生产环境翻车
后台系统中，稳定性优先于缓存

十、后续优化建议

如必须使用 keep-alive：

明确所有页面组件的 name
从 to.matched[].components.default.name 获取
或使用 Pinia 缓存状态，而非组件实例

一句话总结：

这是一次典型的「开发环境掩盖问题，生产环境放大问题」的 keep-alive 使用边界错误。