运行时问题

本页介绍使用 Rspack 构建的应用在运行时可能遇到的问题及处理方式。

Chunk 加载失败

ChunkLoadError 等错误表示异步 chunk 未能加载，但仅凭报错无法确定原因。可以先打开浏览器的 Network 面板，查看失败的请求，再根据具体情况处理：

请求地址不正确：检查请求的域名和路径是否与资源的实际访问地址一致。如果不一致，请检查 output.publicPath 配置。
文件不存在或响应内容不正确：如果返回 404，检查服务器或 CDN 上是否存在对应文件；如果返回的是 HTML，而不是请求的 JavaScript 或 CSS 文件，检查服务器的路由配置。如果是部署时删除了旧文件，请参阅下方的部署示例。
网络异常：如果请求超时、连接失败或服务器返回错误，检查网络连接以及服务器、CDN 是否正常提供服务。
浏览器扩展拦截：暂时关闭广告拦截等可能阻止请求的扩展后重试，确认是否由扩展导致。

请求返回 200，仍出现 `ChunkLoadError`

Network 面板中显示 HTTP 200，并不代表 chunk 已经加载成功。服务器可能返回了 HTML 或错误的 JavaScript 文件，脚本也可能在执行时报错。

可以按下面的顺序排查：

在 Network 面板中打开对应请求，确认响应内容是当前应用版本的 chunk，而不是 HTML、空内容或其他版本的 JavaScript 文件。
查看 Console 中是否有更早出现的 JavaScript 错误。即使下载到了正确的文件，语法错误或执行错误也可能导致加载失败。

浏览器默认通过 <script> 标签加载 JavaScript chunk。如果浏览器成功加载了脚本，但脚本没有包含所需的 chunk，例如服务器返回了空的 JavaScript 文件，Rspack 仍会报出 ChunkLoadError，错误对象的 type 为 'missing'。其中的 request 属性记录了请求地址，可以用来定位 Network 面板中的对应请求。

部署后出现 `ChunkLoadError`

一种常见情况是：用户先打开页面，随后应用部署了新版本，但用户没有刷新页面。此时页面仍然运行旧版本的代码。如果用户再切换到通过 import() 加载的路由，页面就会请求旧版本的 chunk，而这些文件可能已经在部署时被删除。

以通过 import() 加载设置页的应用为例：

用户打开第一个版本的应用。这个版本的代码指向 settings.a1b2.js，但用户还没有访问设置页，因此尚未加载这个 chunk。
部署第二个版本，设置页对应的 chunk 变为 settings.c3d4.js，同时删除了旧文件 settings.a1b2.js。
用户没有刷新页面，直接进入设置页。已打开的页面仍然请求 settings.a1b2.js，服务器返回 404，import() 返回的 Promise 因 ChunkLoadError 被拒绝。

部署时减少加载失败

为了让旧页面和新页面都能加载各自需要的资源，可以通过 output.filename 和 output.chunkFilename，为入口文件和异步 chunk 设置包含内容哈希的文件名。这样，内容发生变化的文件会使用新的名称，新旧文件就能同时保留，不会相互覆盖。

部署后，这些旧文件还需要保留一段时间，因为尚未刷新的页面可能在之后才请求它们。具体保留多久，可以根据用户通常会保持页面打开多长时间来决定。如果部署时就删除旧文件，即使文件名中包含内容哈希，旧页面也无法继续加载它们。

页面中处理加载失败

如果使用框架或路由，先查看它们是否已提供加载失败的处理方式。对于应用直接调用的 import()，可以在 .catch() 回调中处理错误，并沿用已有的错误提示方式。如果确认是部署时删除了旧 chunk，可以提示用户刷新页面以加载新版本。

要让刷新生效，还需要确保浏览器能够获取更新后的 HTML。如果缓存仍然返回旧 HTML，页面可能再次加载旧版本代码，继续请求同一批已删除的文件。

网络故障或资源 URL 配置错误也会导致 chunk 加载失败，而刷新页面并不一定能解决这些问题。如果每次失败都自动刷新，页面可能一直刷新却无法恢复。

无法自动确定 publicPath

设置 output.publicPath: 'auto' 后，Rspack 会根据当前脚本的地址推导其他资源的加载地址。如果无法获取脚本地址，就会报出 Automatic publicPath is not supported in this browser 错误。

此时，可以通过 output.publicPath 直接指定资源的加载地址。例如，资源的访问路径是 /assets/main.js、/assets/logo.png 时：

rspack.config.mjs

export default {
  output: {
    publicPath: '/assets/',
  },
};

请将 /assets/ 替换为应用实际使用的路径，也可以填写完整的 CDN URL。更多示例请参阅资源基础路径。

#运行时问题

#Chunk 加载失败

#请求返回 200，仍出现 ChunkLoadError

#部署后出现 ChunkLoadError

#部署时减少加载失败

#页面中处理加载失败