修复 "Failed to Fetch Dynamically Imported Module" 错误
修复 Vite 的 Failed to fetch dynamically imported module 错误。识别版本不匹配、路径错误、HTML 回退和网络故障,并保留旧资源、限制重载循环。
“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/' }); -
.jsURL 返回了 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/html | SPA 回退或 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 上禁用扩展,或使用干净的浏览器配置文件进行测试。开发环境中不会出现版本偏差,因为没有任何东西会在已打开的标签页下替换构建。
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