> For AI agents: the complete documentation index is available at https://rspack.rs/zh/llms.txt, the full documentation bundle is available at https://rspack.rs/zh/llms-full.txt.

# 运行时问题 \{#runtime-issues}

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

## Chunk 加载失败 \{#chunk-loading-failures}

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

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

### 部署后出现 `ChunkLoadError` \{#chunkloaderror-after-deployment}

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

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

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

#### 部署时减少加载失败 \{#preventing-failures-during-deployment}

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

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

### 页面中处理加载失败 \{#handling-failures-in-the-page}

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

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

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