Vue+Vite生产环境代码分割缓存问题：动态导入模块失败

问题背景 #

使用Vue + Vite开发时，给路由配置了动态导入实现代码分割：

{ 
  path: "settings", 
  name: "settings", 
  component: () => import("../views/SettingsView.vue"), 
},

构建后组件文件会带上哈希（比如SettingsView-4eff3305.js），但部署新版本后，浏览器缓存了旧路由表，导航时会请求旧哈希文件，触发TypeError: Failed to fetch dynamically imported module错误，刷新页面虽能解决，但用户体验差，且不想保留旧文件等缓存过期。

1. 覆盖路由组件导入并重试的可行性分析 #

这个方案可行但确实繁琐，具体流程大概是：

• 用router.onError捕获动态导入错误，从错误信息里提取失效的旧文件名（比如从请求失败的URL中拆分）
• 读取manifest.json，匹配对应路由组件的新哈希文件名
• 修改路由表中对应路由的component字段，替换为新的导入路径后重试导航

但这里有个关键问题：manifest.json本身也会被浏览器缓存，所以必须给它配置强制不缓存的响应头（比如Cache-Control: no-cache, no-store, must-revalidate），或者请求时加时间戳参数（fetch('/manifest.json?' + Date.now())），才能确保每次拿到最新的映射关系。

整体来说，这个方案需要处理的细节多，维护成本高，不推荐作为首选。

2. Vue/Vite 中的更优解决方案 #

方案一：服务器缓存策略 + Vite 基础配置

Vite默认会给带哈希的静态资源设置Cache-Control: max-age=31536000, immutable（长缓存），这部分没问题。核心是确保入口文件不被缓存：

• 在服务器（Nginx/Apache等）配置中，给index.html和manifest.json设置Cache-Control: no-cache，让浏览器每次都请求最新的入口文件，入口文件里的资源引用都是新哈希的，自然不会出现旧路由表的问题。
• 同时在vite.config.js中开启manifest功能，方便后续做版本检测：

export default defineConfig({
  build: {
    manifest: true,
  },
});

方案二：全局捕获错误，强制刷新

用router.onError捕获动态导入失败的错误，直接触发页面刷新，让浏览器加载最新的入口文件和路由表，代码示例：

router.onError((error) => {
  if (error.message.includes('Failed to fetch dynamically imported module')) {
    alert('应用已更新，即将刷新页面获取最新版本');
    window.location.reload(true); // 强制跳过缓存刷新
  }
});

这种方法简单直接，避免了复杂的路由修改逻辑，用户体验也比局部重试更稳定，因为刷新后整个应用都是最新状态。

方案三：主动版本检测

在应用初始化时，对比本地存储的版本和最新版本，主动提示用户刷新：

async function checkAppUpdate() {
  // 加时间戳避免缓存manifest
  const res = await fetch('/manifest.json?' + Date.now());
  const manifest = await res.json();
  const currentVersion = JSON.stringify(manifest);
  const savedVersion = localStorage.getItem('app_version');

  if (savedVersion && savedVersion !== currentVersion) {
    if (confirm('应用已更新，是否立即刷新获取最新功能？')) {
      localStorage.setItem('app_version', currentVersion);
      window.location.reload(true);
    }
  } else {
    localStorage.setItem('app_version', currentVersion);
  }
}

// 应用启动时执行
checkAppUpdate();

这种方法更主动，能在用户操作前就检测到更新，避免导航时出错的情况。

总结 #

• 覆盖路由组件导入重试的方案繁琐且易出问题，不推荐。
• 最优实践是服务器配置入口文件不缓存 + 全局错误捕获刷新，或者搭配主动版本检测，这两种方法实现简单，能有效保证用户获取最新版本，同时保留哈希文件名的长缓存特性。

内容的提问来源于stack exchange，提问作者Perfect-Plant-4131