12k
All articles

修复 "Failed to Fetch Dynamically Imported Module" 错误

修复 Vite 的 Failed to fetch dynamically imported module 错误。识别版本不匹配、路径错误、HTML 回退和网络故障,并保留旧资源、限制重载循环。

OpenReplay Team
OpenReplay Team
修复 "Failed to Fetch Dynamically Imported Module" 错误

“Failed to fetch dynamically imported module” 表示浏览器无法加载通过 import() 请求的 JavaScript chunk。在生产环境中,最常见的原因是新的部署删除了某个 chunk,而一个已打开的标签页仍在请求它。

这种情况很常见:你刚发布一个版本,几分钟内错误监控就开始大量告警,可你自己逐个点击路由,一切都正常。新构建本身并没有问题,失败的请求来自那些加载了上一个构建的标签页。

本文将介绍部署时触发该错误的机制,三种逐层递进的修复方案(保留旧资源、重新加载处理器、防循环保护),会产生相同报错的其他少见原因,以及一张借助 Network 面板区分各类原因的对照表。

要点速览

  • “Failed to fetch dynamically imported module” 最常见的原因是版本偏差(version skew):上一次部署时打开的标签页按哈希文件名请求某个懒加载 chunk,而该文件已不在服务器上。
  • 为 index.html 设置 Cache-Control: no-cache 并保留上一次部署的资源,可以在任何客户端代码运行之前就阻止大部分版本偏差导致的失败。
  • Vite 的 vite:preloadError 事件允许你在 chunk 加载失败时重新加载页面,但处理器需要一个基于 sessionStorage 时间戳的保护机制,避免无限重载。
  • 如果失败的 .js 请求返回 200 且 Content-Type: text/html,那是服务器或 CDN 的回退(fallback)配置问题,而不是版本偏差。
  • 重试失败的动态导入无法解决版本偏差,因为旧构建引用的文件已经不存在了。

为什么一次部署会让已打开的标签页出错?

Vite 故障排查指南列出了 TypeError: Failed to fetch dynamically imported module 的三种原因:版本偏差、网络状况不佳,以及浏览器扩展拦截请求。其中,版本偏差正是导致发布后错误激增的那一个。

具体过程如下:用户从构建 A 加载了 index.html,其中引用了 assets/Settings-a1b2c3.js 等 chunk。随后你部署了构建 B,内容哈希随之改变。而用户的标签页仍在运行构建 A。当用户导航到某个懒加载路由时,浏览器请求 Settings-a1b2c3.js,得到 404,导入随即被 reject:

TypeError: Failed to fetch dynamically imported module: https://example.com/assets/Settings-a1b2c3.js

以上是 Chromium 的报错措辞。其他浏览器对同一失败的描述各不相同,因此在错误监控中应按原因归类,而不是按具体的错误字符串。

这个问题在本地几乎无法复现,因为全新的页面加载总是从同一个构建中获取 HTML 和 chunk。只有在部署前加载了旧构建、并在部署后请求懒加载路由的标签页中才会出现。它也与 Vite 的 “Failed to resolve import” 错误无关:那是构建时的模块解析失败,而本文讨论的错误发生在运行时。

修复 1:保留旧资源并让 HTML 重新验证

解决版本偏差成本最低的方式在服务端:保留上一个构建的 chunk,并以 Cache-Control: no-cache 提供 HTML。如果构建 B 上线后构建 A 的 chunk 仍然存在,旧标签页就能继续正常工作。Vite 的加载错误处理说明指出,许多托管平台会删除上一次部署的资源,并建议为 HTML 设置 Cache-Control: no-cache。

为 index.html 设置 Cache-Control: no-cache 后,浏览器每次加载时都会重新验证 HTML。这样页面重新加载时就能拿到新构建的 chunk 名称,而不是已被删除的旧名称。带哈希的资源则恰好相反:它们的 URL 会随内容变化而变化,因此可以放心地使用较长的 max-age 并配合 MDN 中介绍的 immutable 指令。

location = /index.html {
  add_header Cache-Control "no-cache";
}

location /assets/ {
  add_header Cache-Control "public, max-age=31536000, immutable";
  try_files $uri =404;
}

location / {
  try_files $uri $uri/ /index.html;
}

让部署以增量方式进行:将新的 assets/ 与旧文件一同上传,然后定期清理旧文件。保留多久需要自行权衡,原则是要比用户实际保持标签页打开的时长更久。

修复 2:在 vite:preloadError 时重新加载一次

在客户端,当动态导入加载失败时,Vite 会在 window 上派发 vite:preloadError 事件,在该事件的处理器中重新加载页面即可从版本偏差中恢复。服务端保留旧资源固然有帮助,但旧 chunk 终究会被清理。原始错误位于 event.payload 中,调用 event.preventDefault() 可以阻止 Vite 抛出该错误。构建指南建议在此处理器中重新加载页面。

重新加载会获取最新的 index.html,其中引用的是构建 B 的 chunk,从而解决版本偏差。而重试导入则无济于事,因为构建 A 指向的文件在服务器上已不复存在,只有加载新的 HTML 才能解决问题。(原地重试只对临时性网络故障有效。HTML 规范曾经会缓存失败的模块请求,whatwg/html#10327 修改了这一行为,但各浏览器的支持情况不一,详见 MDN 的 import() 兼容性表。)

修复 3:防止重载循环

vite:preloadError 的重载处理器需要防止重载循环。如果 HTML 本身是过期的(例如边缘缓存忽略了 no-cache),或者某个 chunk 在新旧两个构建中都不存在,重新加载后会以同样的方式失败,页面就会无限重载。有些框架内置了这种恢复机制,因此请先查阅所用框架的文档。例如,Nuxt 默认会在 chunk 加载出错时重新加载,其重载辅助函数会在 sessionStorage 中记录每次重载,并在 10 秒内忽略重复的重载请求。如果你使用的是原生 Vite 搭配 React、Vue 或 Svelte,可以将以下代码添加到入口文件中:

// src/main.js
const RELOAD_KEY = 'chunk-reload-at';
const RELOAD_WINDOW_MS = 10_000; // tunable, not a standard value

function lastReload() {
  try {
    return Number(sessionStorage.getItem(RELOAD_KEY)) || 0;
  } catch {
    return 0;
  }
}

function markReload() {
  try {
    sessionStorage.setItem(RELOAD_KEY, String(Date.now()));
    return true;
  } catch {
    return false; // storage unavailable: don't risk a loop
  }
}

window.addEventListener('vite:preloadError', (event) => {
  console.error(event.payload); // send to your error tracker instead

  const recentlyReloaded = Date.now() - lastReload() < RELOAD_WINDOW_MS;
  if (!recentlyReloaded && markReload()) {
    event.preventDefault();
    window.location.reload();
  }
  // Otherwise let the error reach the app's error boundary.
});

该处理器会立即重新加载页面,因此不依赖于 preventDefault() 之后导入最终解析为何值。如果在时间窗口内已经重载过一次,处理器就不会拦截该错误,错误会继续向上传播,由错误边界(error boundary)显示提示信息:

import React from 'react';

class ChunkErrorBoundary extends React.Component {
  state = { failed: false };
  static getDerivedStateFromError() {
    return { failed: true };
  }
  render() {
    if (!this.state.failed) return this.props.children;
    return (
      <div role="alert">
        <p>A new version is available.</p>
        <button onClick={() => window.location.reload()}>Refresh</button>
      </div>
    );
  }
}

Refresh 按钮由用户主动触发,因此保护机制无需拦截它。Vue 和 Svelte 也有对应的错误处理钩子。无论使用哪种框架,都应在路由或错误边界层面处理该 rejection,因为 Vite 文档并未明确说明是否每一次失败的动态导入都会触发该事件。

产生相同错误的其他少见原因

“Failed to fetch dynamically imported module” 也可能源于与部署无关的路径、服务器或客户端问题。这类失败通常也会影响发布之后才开始的会话。

  • base 路径错误。 如果失败的 chunk URL 缺少应用部署所在的路径前缀,原因在于 Vite 配置中的 base 选项,而非过期的部署。请将其设置为与部署路径一致,或在构建时传入 --base,详见 Vite 公共基础路径文档:

    // vite.config.js — app served from https://example.com/app/
    // without base: /assets/c-x1y2.js     (404)
    // with base:    /app/assets/c-x1y2.js
    import { defineConfig } from 'vite';
    
    export default defineConfig({ base: '/app/' });
  • .js URL 返回了 HTML。 SPA 回退规则或 CDN 重写用 index.html 响应了未知的 chunk 路径。由于响应的 MIME 类型不是 JavaScript,浏览器会拒绝将其作为模块加载。请将 /assets/ 排除在回退规则之外,让缺失的文件返回真正的 404,就像上文的 nginx 配置那样。

  • 广告拦截器。 浏览器扩展常常会拦截文件名中包含 “ad” 或 “track” 等词的文件。Vite 建议通过 build.rolldownOptions.output.chunkFileNames 重命名 chunk。在 Vite 7 及更早版本中,该选项为 build.rollupOptions,Vite 8 仍将其作为已弃用的别名予以支持。

    build: { rolldownOptions: { output: { chunkFileNames: 'assets/c-[hash].js' } } }
  • 网络中断。 这类失败是间歇性的,可能出现在任意文件名上,且没有 HTTP 状态码。带保护的重新加载同样可以覆盖这种情况。

如何判断属于哪种原因?

打开 Network 面板,找到失败的 chunk 请求,检查两项内容:状态码和 Content-Type。结合这两项即可确定原因。

失败的 chunk 请求表现可能原因修复方式
404,文件名为旧构建的哈希文件名版本偏差修复 1 至 3
200,Content-Type: text/htmlSPA 回退或 CDN 重写让 /assets/ 下返回真正的 404
404,URL 缺少部署子路径base 配置错误设置 base
被拦截,文件名包含类似广告的词浏览器扩展通过 chunkFileNames 重命名
失败且无状态码,间歇性出现网络问题带保护的重新加载

由于你通常无法亲自复现该问题,只能依靠生产环境数据来判断属于哪种情况。作为完善的错误日志实践的一部分,请为每条错误记录发布版本标识。将错误监控与会话回放结合,可以看出失败是否集中出现在部署之后、且来自部署之前就已开始的会话——这正是版本偏差的典型特征。会话回放还能显示保护机制是否触发了一次重载并成功恢复。与 “ResizeObserver loop completed” 错误类似,这是一种噪声较大的生产环境错误,应当对其进行归类,而不是直接屏蔽。

从根源上解决问题

“Failed to fetch dynamically imported module” 通常是在客户端代码中暴露出来的部署问题。先从服务端入手:保留旧资源、为 index.html 设置 no-cache,并确保 /assets/ 永远不会回退到 HTML。然后添加带保护的 vite:preloadError 处理器和错误边界作为兜底。在修改任何配置之前,先在 Network 面板中打开失败的请求,根据其状态码和内容类型确认具体原因。

常见问题

这与 webpack 的 ChunkLoadError 是同一个问题吗?

是的,根本原因相同,只是错误来源不同。webpack 通过自身的运行时加载 chunk,加载失败时会以 ChunkLoadError 进行 reject,并附带类似 'Loading chunk 42 failed' 的信息。Vite 的生产构建使用原生 import(),因此显示的是浏览器自身的错误。两者的服务端修复方式相同:保留旧资源并让 HTML 重新验证。vite:preloadError 事件仅存在于 Vite 中。

Service Worker 或 chunk 预取能否防止版本偏差错误?

这两者都是 Vite 故障排查指南中列出的缓解手段。预取并缓存全部资源的 Service Worker 可以让已打开的标签页继续访问旧构建的 chunk,即使服务器已将其删除。预取动态 chunk 可以在部署删除它们之前就完成加载,但如果浏览器因 Cache-Control 头缓存了 HTML,这种方式就无济于事。

为什么在没有部署的 Vite 开发服务器上也会出现这个错误?

在开发服务器上,常见原因是浏览器扩展。Vite 故障排查指南指出,广告拦截器等扩展可能会阻止 Vite 客户端向开发服务器发送请求,从而产生相同的错误信息。要确认这一点,可以在 localhost 上禁用扩展,或使用干净的浏览器配置文件进行测试。开发环境中不会出现版本偏差,因为没有任何东西会在已打开的标签页下替换构建。

DevTools for the frontend

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.