WordPress+Vue3+Webpack5项目部署新版本后ChunkLoadError报错求解

问题根因说明 #

为什么配置了Cloudflare缓存还会出现该错误 #

• 部署新版本时你大概率清空了上一版本的dist目录，且主动触发了Cloudflare全量缓存清除，旧版本带hash的chunk文件在源站和CDN都已不存在。旧会话中已经加载的入口文件记录的还是旧chunk的hash值，路由跳转触发懒加载时自然会请求失败。
• 即使没有主动清理CDN缓存，旧chunk的缓存到期后CDN会回源校验，源站已删除对应文件，同样会返回404触发报错。

解决方案 #

1. 构建配置优化 #

首先调整webpack output配置，统一使用[contenthash]作为文件哈希标识，只有文件内容实际变更时才会更新哈希值，避免不必要的hash变动：

output: {
    filename: (chunkData) => {
        // 所有入口文件统一添加contenthash
        return '[name]/[name].[contenthash].js';
    },
    path: path.resolve(__dirname, 'dist'),
    publicPath: '/wp-content/themes/my-theme/dist/',
    // chunk文件也使用contenthash
    chunkFilename: 'main/[contenthash].js',
},

部署时不要清空历史dist目录，至少保留最近3-5个版本的chunk文件，确保旧会话的资源请求能正常命中。

2. 运行时错误捕获处理 #

针对Vue路由懒加载的场景，封装懒加载函数，主动捕获ChunkLoadError：

// 封装懒加载错误处理逻辑
const lazyLoad = (importFunc) => {
  return () => importFunc().catch((error) => {
    if (error.name === 'ChunkLoadError') {
      // 可根据业务需求选择自动刷新，或弹出提示引导用户手动刷新
      alert('站点已更新，请刷新页面后使用');
      window.location.reload();
    }
    throw error;
  });
};

// 路由配置中替换原有懒加载写法
const routes = [
  {
    path: '/example',
    component: lazyLoad(() => import('./views/Example.vue'))
  }
]

也可以全局监听未处理的Promise rejection，做兜底捕获：

window.addEventListener('unhandledrejection', (event) => {
  if (event.reason?.name === 'ChunkLoadError') {
    alert('站点已更新，请刷新页面后使用');
    window.location.reload();
    event.preventDefault();
  }
})

3. CDN缓存策略调整 #

在Cloudflare侧针对带hash的js、css等静态资源配置专属缓存规则：

• 设置Cache-Control: public, max-age=31536000, immutable，告知浏览器和CDN该类资源可永久缓存，无需主动回源校验。
• 部署新版本时仅清除入口HTML、以及不带hash的静态资源的CDN缓存，不要全量清除所有资源缓存，保留旧chunk的缓存直到自然过期。

4. 版本检测兜底 #

如果受服务器存储限制无法保留历史chunk文件，可以在构建时生成版本标识文件，前端做主动校验：

• 构建阶段在dist目录生成version.json，写入当前构建的contenthash值。
• 前端每次路由跳转前请求该文件，对比当前页面加载的版本号，若不一致则提示用户刷新页面。

内容的提问来源于stack exchange，提问作者Senate No. 7