Vue Suspense 在组合式 API 中如何处理异步组件加载异常

Vue 3 的 Suspense 并不会负责捕获异步加载异常，它主要用于协调组件“加载中”和“加载完成”两种状态；如果出现错误，通常需要通过 errorCaptured、onErrorCaptured 或错误边界来处理。由于 fallback 插槽不会对 reject 状态做出响应，因此更推荐结合 ref 控制错误提示视图，并封装重试逻辑来提升稳定性。

在 Vue 3 中，Suspense 本质上不会主动帮你捕获或处理异步组件加载过程中的异常，例如网络请求失败、动态模块加载报错、模块解析异常等。它的核心作用更偏向于管理“等待中”和“已准备好”这两种渲染状态。真正遇到异步组件加载失败时，仍然需要借助 errorCaptured 钩子、onErrorCaptured，或者在更外层使用错误边界机制进行处理，不能把异常兜底的责任放在 Suspense 插槽本身上。

异常不会自动显示在 fallback 中

Suspense 的 #fallback 插槽只会在组件处于“加载中”阶段时显示。一旦异步操作被拒绝（reject），组件挂载流程会中断并抛出错误，这时候 fallback 并不会继续渲染，页面很可能出现白屏、报错，或者渲染被直接打断。

• defineAsyncComponent 返回的异步组件加载失败（例如 404、语法错误）→ 会触发 unhandled error
• async setup() 中主动 throw 错误 → 同样会中断渲染流程，不会进入 fallback
• Suspense 没有内置的 error 插槽，也不提供 onError 回调 API

推荐的异常处理方式

更实用的做法是通过 errorCaptured 钩子拦截子组件抛出的异步异常，并在界面上优雅降级，展示清晰的错误提示：

• 在父组件中使用 onErrorCaptured（组合式 API）监听并处理子组件错误
• 结合 ref 控制是否显示自定义错误视图，从而替代默认的崩溃或空白页面
• 支持重试：通过按钮重新触发 defineAsyncComponent 的加载逻辑，改善用户体验

示例：

更健壮的方案：封装带错误处理的异步组件

如果项目中经常使用异步组件，建议把错误重试、加载超时和兜底展示统一封装到自定义 Hook 或工厂函数中，避免每个页面都重复编写 onErrorCaptured 相关逻辑：

• 使用 defineAsyncComponent({ loader, errorComponent, timeout })（Vue 3.4+ 支持）配置超时处理和错误组件
• 自行封装一个 useAsyncComponent，统一返回加载状态、错误信息以及重试方法
• 在路由层统一处理，例如在 router.beforeEach 或布局组件中集中拦截异步组件异常

注意边界情况

需要注意的是，并不是所有错误都能被 errorCaptured 完整捕获，以下边界场景仍需单独处理：

• 顶层 await 报错（如 const data = await fetch(...)）→ 必须在 setup() 内使用 try/catch 包裹，否则可能直接导致应用崩溃
• 动态 import 路径错误（如路径拼写错误）→ 这类问题属于模块解析错误，通常需要构建工具给出提示，运行时只能尽量通过 onErrorCaptured 拦截
• 在 SSR 环境下，Suspense 的行为与客户端并不完全一致，因此错误处理逻辑需要区分服务端与客户端场景