Vue 基础体系 · 第 33/70 篇。示例基于 Vue 3、Composition API、TypeScript 与现代 Vite 工具链；版本敏感能力会单独标注。

Vue Suspense 与异步组件：加载、错误、超时和嵌套边界

在 Vue 3 中，异步组件和 Suspense 解决的是两个相关但不同的问题：

• 异步组件决定“组件代码如何异步加载，以及加载失败后如何重试或显示错误”。
• **Suspense**决定“组件树中存在异步依赖时，页面应该显示哪一部分内容”。

如果只使用异步组件，可以获得组件级的加载和错误状态；如果使用 Suspense，则可以把多个异步依赖组合成一个边界，统一控制 fallback（回退内容）和内容切换时机。

---

一、先建立三个核心概念

1. 异步组件是什么

普通组件在渲染时已经有完整的组件定义：

import UserPanel from './UserPanel.vue'

异步组件则把组件定义推迟到真正需要渲染时再加载：

import { defineAsyncComponent } from 'vue'

const UserPanel = defineAsyncComponent(() => import('./UserPanel.vue'))

这里的 () => import('./UserPanel.vue') 是一个返回 Promise 的加载器。现代 Vite 会把 UserPanel.vue 拆成独立的代码块，浏览器需要渲染 UserPanel 时才请求该代码块。

因此，异步组件至少经历以下状态：

未请求
  ↓
加载中
  ├── 成功 → 使用真正的组件渲染
  └── 失败 → 进入错误处理

异步组件解决的是组件定义的延迟加载，例如：

• 路由页面按需加载；
• 很少打开的设置面板；
• 体积较大的编辑器、图表或地图组件；
• 只在特定权限下出现的管理界面。

它不等同于“组件内部的数据请求”。一个已经加载完成的组件，仍然可能在 setup() 中请求数据。

---

2. Suspense 是什么

Suspense 是一个特殊的内置组件，用于等待后代组件的异步依赖完成。

一个组件被 Suspense 视为异步依赖，主要有两种情况：

1. 组件使用异步 setup()：

   export default {
     async setup() {
       const response = await fetch('/api/user')
       const user = await response.json()
   
       return { user }
     }
   }
   

2. Suspense 的后代包含默认行为的异步组件：

   const UserPanel = defineAsyncComponent(
     () => import('./UserPanel.vue')
   )
   

Suspense 有两个主要插槽：

<Suspense>
  <template #default>
    <!-- 异步内容 -->
  </template>

  <template #fallback>
    <!-- 等待期间显示的内容 -->
  </template>
</Suspense>

它关注的是一棵组件子树是否已经可以显示完整内容，而不是单个 Promise 的实现细节。

---

3. “边界”是什么意思

这里的“边界”指一个 Suspense 实例负责管理的异步组件子树。

边界内部可能有多个异步依赖：

Suspense 边界
├── 异步组件 A
├── 普通组件
└── 异步组件 B

只有当 A 和 B 都完成后，默认内容才算准备好。可以用集合表示：

$$P = \{p_1, p_2, \ldots, p_n\}$$

其中每个 $p_i$ 是一个异步依赖。边界进入 resolved（已解析）状态的条件是：

$$\forall p_i \in P,\quad p_i \text{ 已完成}$$

只要有一个依赖仍处于 pending（等待中），边界就不能认为整棵内容树已经完成。

---

二、异步组件的完整配置

defineAsyncComponent 支持简单形式和对象形式。

1. 简单形式

import { defineAsyncComponent } from 'vue'

const SettingsPanel = defineAsyncComponent(
  () => import('./SettingsPanel.vue')
)

简单形式适合只需要代码分割、不需要自定义加载和错误界面的场景。

2. 对象形式

import { defineAsyncComponent } from 'vue'
import LoadingPanel from './LoadingPanel.vue'
import AsyncError from './AsyncError.vue'

const SettingsPanel = defineAsyncComponent({
  loader: () => import('./SettingsPanel.vue'),

  loadingComponent: LoadingPanel,

  errorComponent: AsyncError,

  delay: 200,

  timeout: 8000,

  suspensible: true,

  onError(error, retry, fail, attempts) {
    if (attempts <= 2) {
      retry()
    } else {
      fail(error)
    }
  }
})

各字段的语义如下：

字段	作用
loader	返回组件定义 Promise 的加载函数
loadingComponent	异步组件自身的加载中界面
errorComponent	异步组件加载失败后的界面
delay	延迟多久后才显示 loadingComponent
timeout	超过指定时间后将加载视为失败
suspensible	是否把异步等待交给父级 Suspense
onError	自定义失败、重试和最终失败逻辑

delay 和 timeout 的单位都是毫秒。

---

三、异步组件的加载状态、错误状态和超时

1. delay 不是超时

以下配置表示：

const ChartPanel = defineAsyncComponent({
  loader: () => import('./ChartPanel.vue'),
  loadingComponent: LoadingPanel,
  delay: 200,
  timeout: 10_000
})

两项配置分别控制不同问题：

• 前 200 毫秒内不显示加载组件；
• 200 毫秒后如果仍未完成，显示 LoadingPanel；
• 10 秒后仍未完成，则认为加载失败。

delay 的目的通常是避免快速加载时页面发生闪烁。它不会改变网络请求，也不会取消加载。

timeout 也不会取消浏览器已经发出的动态导入请求。它只是让 Vue 将该异步组件标记为失败，并进入错误处理路径。底层请求是否继续，由模块加载器和浏览器处理。

---

2. errorComponent 的使用条件

一个独立使用的异步组件可以这样配置：

const ReportPanel = defineAsyncComponent({
  loader: () => import('./ReportPanel.vue'),
  loadingComponent: LoadingPanel,
  errorComponent: ReportLoadError,
  delay: 200,
  timeout: 5000
})

模板：

<template>
  <ReportPanel />
</template>

当加载器失败，且没有通过 onError 重试成功时，Vue 会渲染 ReportLoadError。

错误组件可以通过 error prop 获取异常对象：

<script setup lang="ts">
defineProps<{
  error: unknown
}>()
</script>

<template>
  <section role="alert">
    报表加载失败。
  </section>
</template>

错误组件适合显示“这个异步组件自己的加载失败状态”。如果页面需要统一管理多个异步依赖的错误，则应使用错误捕获机制，而不能把所有错误状态都塞进每个异步组件的 errorComponent。

---

3. onError 的重试模型

onError 接收四个参数：

onError(error, retry, fail, attempts)

含义是：

• error：本次加载错误；
• retry()：重新调用加载器；
• fail(error)：放弃重试，让错误继续进入失败处理；
• attempts：已经尝试的次数。

一个更安全的重试示例：

const AdminPanel = defineAsyncComponent({
  loader: () => import('./AdminPanel.vue'),

  onError(error, retry, fail, attempts) {
    const isNetworkError = error instanceof TypeError

    if (isNetworkError && attempts < 3) {
      const delay = attempts * 1000

      window.setTimeout(() => {
        retry()
      }, delay)

      return
    }

    fail(error)
  }
})

状态变化可以写成：

第一次加载
  ↓ 失败
attempts = 1
  ↓ retry()
第二次加载
  ↓ 失败
attempts = 2
  ↓ retry()
第三次加载
  ↓ 失败
attempts = 3
  ↓ fail(error)
最终失败

重试并不总是合理：

• 网络暂时抖动时，有限次数重试可能有效；
• 代码块不存在、版本部署不一致或权限错误时，重试通常不会改变结果；
• 无限重试会让页面长期处于加载状态，并放大服务器压力。

因此，重试必须有上限，并且最终要让用户看到明确的失败状态。

---

四、Suspense 的运行过程

考虑下面的组件：

<!-- UserPanel.vue -->
<script setup lang="ts">
const response = await fetch('/api/user')

if (!response.ok) {
  throw new Error(`请求失败：${response.status}`)
}

const user = await response.json()
</script>

<template>
  <section>
    <h2>{{ user.name }}</h2>
    <p>{{ user.email }}</p>
  </section>
</template>

它使用了顶层 await。在 Vue 3 的 <script setup> 中，顶层 await 会使组件的 setup() 变成异步过程，因此它需要被 Suspense 祖先包围，才能让 Vue 统一管理等待状态。

父组件：

<script setup lang="ts">
import UserPanel from './UserPanel.vue'
</script>

<template>
  <Suspense>
    <template #default>
      <UserPanel />
    </template>

    <template #fallback>
      <p>正在加载用户信息……</p>
    </template>
  </Suspense>
</template>

初始渲染时，过程大致如下：

1. 创建 Suspense 边界
2. 渲染 default 插槽
3. UserPanel 执行异步 setup()
4. UserPanel 尚未完成
5. Suspense 显示 fallback
6. fetch 完成并返回用户数据
7. UserPanel 完成 setup()
8. Suspense 切换到 default 内容

fallback 并不是“异步组件内部的 loadingComponent”。它是整个 Suspense 边界在等待期间的替代内容。

---

Suspense 等待什么

Suspense 只等待它能够识别的异步依赖。常见依赖包括：

• 异步 setup()；
• 顶层 await；
• 默认 suspensible: true 的异步组件；
• 后代 Suspense 对父边界暴露的未完成状态。

但普通事件处理函数中的 Promise 不会自动被 Suspense 等待：

<script setup lang="ts">
async function save() {
  await fetch('/api/save', {
    method: 'POST'
  })
}
</script>

<template>
  <button @click="save">保存</button>
</template>

这里的 save() 发生在用户点击之后，不属于组件初始渲染过程。Suspense 不会因为保存请求未完成而显示 fallback。

同样，下面的 onMounted 请求也不会自动成为 Suspense 的异步依赖：

import { onMounted, ref } from 'vue'

const user = ref(null)

onMounted(async () => {
  const response = await fetch('/api/user')
  user.value = await response.json()
})

如果希望初始渲染等待数据，应把请求放入异步 setup() 或显式维护组件自己的加载状态。

---

五、Suspense 与异步组件的关系

1. 默认情况下，异步组件会交给 Suspense

const UserPanel = defineAsyncComponent({
  loader: () => import('./UserPanel.vue'),
  loadingComponent: LoadingPanel,
  errorComponent: ErrorPanel
})

当它位于 Suspense 内部时，默认的 suspensible 为 true。此时：

<Suspense>
  <UserPanel />

  <template #fallback>
    <PageSkeleton />
  </template>
</Suspense>

等待期间通常由 Suspense 的 fallback 负责显示，而不是由异步组件自己的 loadingComponent 负责显示。

这产生一个重要区别：

使用方式	加载状态主要由谁控制
异步组件不在 Suspense 中	异步组件自己的 loadingComponent
异步组件在默认 Suspense 中	Suspense 的 fallback
设置 suspensible: false	异步组件恢复自己的加载和错误状态

如果希望一个异步组件即使位于 Suspense 内，也独立显示自己的加载状态：

const IndependentPanel = defineAsyncComponent({
  loader: () => import('./IndependentPanel.vue'),
  loadingComponent: LoadingPanel,
  errorComponent: ErrorPanel,
  suspensible: false
})

此时它不会把自己的加载等待交给父级 Suspense。

---

2. suspensible: false 的代价

设置 suspensible: false 后，组件可以独立显示：

• delay 控制的加载组件；
• timeout 触发的错误组件；
• 自己的重试状态。

但父级 Suspense 不再等待它。这意味着父级可能先显示“页面已完成”的其他内容，而该异步组件仍在加载：

父级 Suspense
├── 已完成的页面内容
└── suspensible: false 的异步组件
    └── 自己显示 LoadingPanel

因此，suspensible: false 不是“更强的 Suspense”，而是把控制权从父边界移回组件本身。

---

六、Suspense 的超时语义

Suspense 的 timeout 主要影响已经解析过的边界再次进入等待状态时的 fallback 切换。

示例：

<Suspense :timeout="800">
  <template #default>
    <UserPanel :user-id="userId" />
  </template>

  <template #fallback>
    <p>正在切换用户……</p>
  </template>
</Suspense>

可以将边界抽象为两个状态：

Pending：当前内容尚未完成
Resolved：当前内容已经完成

初次渲染

初始状态：Pending
↓
直接显示 fallback
↓
所有异步依赖完成
↓
进入 Resolved，显示 default

初次渲染时，Suspense 会直接使用 fallback，timeout 不会让初始 fallback 再额外等待 800 毫秒。

已解析内容发生异步更新

假设当前显示的是用户 A，切换到用户 B：

当前状态：Resolved，显示用户 A
↓
用户 B 的异步依赖开始执行
↓
继续保留用户 A 的旧内容
↓ 800ms 内完成
直接切换到用户 B，不显示 fallback

如果超过 800 毫秒：

当前状态：Resolved，显示用户 A
↓
用户 B 的异步依赖开始执行
↓
保留用户 A 的旧内容 800ms
↓
仍未完成
显示 fallback
↓
用户 B 的依赖完成
↓
显示用户 B

这是一种“避免短暂切换闪烁”的机制。它与异步组件的 delay 不同：

• 异步组件的 delay 控制自己的 loading component 何时显示；
• Suspense 的 timeout 控制已解析边界再次等待时，何时从旧内容切换到 fallback。

---

七、错误处理：Suspense 不提供 error slot

Suspense 支持 default 和 fallback 插槽，但没有内置的 #error 插槽：

<!-- 这种写法不是 Vue Suspense 的错误处理 API -->
<Suspense>
  <template #error>
    加载失败
  </template>
</Suspense>

异步依赖失败时，应使用 Vue 的标准错误处理机制：

• onErrorCaptured()；
• app.config.errorHandler；
• 异步组件的 errorComponent；
• 异步组件的 onError。

1. 使用 onErrorCaptured 创建错误边界

下面是一个可以运行的错误边界组件：

<!-- ErrorBoundary.vue -->
<script setup lang="ts">
import { onErrorCaptured, ref } from 'vue'

const error = ref<unknown>(null)
const renderKey = ref(0)

onErrorCaptured((caughtError) => {
  error.value = caughtError

  // 阻止错误继续向更高层的 onErrorCaptured 和全局处理器传播。
  return false
})

function retry() {
  error.value = null
  renderKey.value += 1
}
</script>

<template>
  <section v-if="error" role="alert">
    <p>内容加载失败。</p>
    <button type="button" @click="retry">
      重试
    </button>
  </section>

  <div v-else :key="renderKey">
    <slot />
  </div>
</template>

使用方式：

<script setup lang="ts">
import ErrorBoundary from './ErrorBoundary.vue'
import UserPanel from './UserPanel.vue'
</script>

<template>
  <ErrorBoundary>
    <Suspense :timeout="500">
      <template #default>
        <UserPanel />
      </template>

      <template #fallback>
        <p>正在加载……</p>
      </template>
    </Suspense>
  </ErrorBoundary>
</template>

这里的因果关系是：

UserPanel 的异步 setup 抛出错误
↓
错误向祖先组件传播
↓
ErrorBoundary 的 onErrorCaptured 捕获
↓
error.value 变为非空
↓
ErrorBoundary 改为渲染错误界面

点击重试时，renderKey 变化会强制重新创建插槽中的子树，从而重新执行异步 setup() 或重新尝试异步组件加载。

这不是 Suspense 自己提供的重试机制，而是应用层利用组件重新挂载实现的重试。

---

2. return false 的影响

onErrorCaptured((error) => {
  console.error(error)
  return false
})

return false 表示该错误已经被当前处理器处理，不再继续向上冒泡。

如果不返回 false，错误仍可能继续传递到：

• 更高层的 onErrorCaptured；
• 应用级 app.config.errorHandler；
• 开发环境控制台。

生产应用通常需要决定错误应该由哪一层负责展示，以及是否仍然需要交给全局日志系统。阻止 UI 错误继续传播，不应等同于丢弃错误日志。

---

3. 异步组件的 errorComponent 与 Suspense 错误边界

当异步组件独立使用时，errorComponent 是很直接的错误 UI。

但当异步组件被默认行为的 Suspense 管理时，加载等待由父级边界接管，不能简单假设异步组件的 loadingComponent 和 errorComponent 仍然按照独立使用时的方式工作。尤其是加载器失败时，错误会进入 Vue 的错误处理链路。

因此，若异步组件位于 Suspense 内，可靠的设计是：

• 用 Suspense 管理等待期间的整体界面；
• 用 onErrorCaptured 管理边界错误；
• 用异步组件的 onError 管理有限重试；
• 不要把 errorComponent 当作 Suspense 的错误插槽。

如果确实要求异步组件完全独立控制加载和失败状态，可以设置：

const Panel = defineAsyncComponent({
  loader: () => import('./Panel.vue'),
  loadingComponent: LoadingPanel,
  errorComponent: ErrorPanel,
  suspensible: false
})

---

八、一个完整的 Vite + Vue 3 + TypeScript 示例

下面的示例包含：

• 异步组件代码分割；
• 加载延迟；
• 超时；
• 有限重试；
• Suspense fallback；
• onErrorCaptured 错误边界。

1. 异步组件

// src/components/AsyncUserPanel.ts
import { defineAsyncComponent } from 'vue'
import LoadingPanel from './LoadingPanel.vue'
import AsyncErrorPanel from './AsyncErrorPanel.vue'

export const AsyncUserPanel = defineAsyncComponent({
  loader: () => import('./UserPanel.vue'),

  loadingComponent: LoadingPanel,

  errorComponent: AsyncErrorPanel,

  delay: 200,

  timeout: 8000,

  onError(error, retry, fail, attempts) {
    const canRetry =
      error instanceof TypeError && attempts < 3

    if (canRetry) {
      window.setTimeout(() => {
        retry()
      }, attempts * 1000)

      return
    }

    fail(error)
  }
})

这里假设 TypeError 代表网络层失败。但在真实项目中，不能仅依赖异常类型判断是否可重试，因为不同浏览器、请求库和构建工具可能使用不同的错误对象。更可靠的做法是结合错误码、HTTP 状态和请求上下文。

2. 异步内容组件

<!-- src/components/UserPanel.vue -->
<script setup lang="ts">
const response = await fetch('/api/user')

if (!response.ok) {
  throw new Error(`加载用户失败：HTTP ${response.status}`)
}

const user = await response.json()
</script>

<template>
  <article>
    <h2>{{ user.name }}</h2>
    <p>{{ user.email }}</p>
  </article>
</template>

3. 加载组件

<!-- src/components/LoadingPanel.vue -->
<template>
  <div aria-busy="true">
    正在加载用户信息……
  </div>
</template>

4. 异步组件错误组件

<!-- src/components/AsyncErrorPanel.vue -->
<script setup lang="ts">
defineProps<{
  error: unknown
}>()
</script>

<template>
  <div role="alert">
    用户面板代码加载失败。
  </div>
</template>

5. 页面级使用

<!-- src/App.vue -->
<script setup lang="ts">
import ErrorBoundary from './components/ErrorBoundary.vue'
import { AsyncUserPanel } from './components/AsyncUserPanel'
</script>

<template>
  <main>
    <h1>用户中心</h1>

    <ErrorBoundary>
      <Suspense :timeout="800">
        <template #default>
          <AsyncUserPanel />
        </template>

        <template #fallback>
          <section aria-busy="true">
            页面内容正在准备……
          </section>
        </template>
      </Suspense>
    </ErrorBoundary>
  </main>
</template>

运行前提是：

npm create vite@latest vue-suspense-demo -- --template vue-ts
cd vue-suspense-demo
npm install
npm run dev

并把上述文件放入 src 目录。示例中的 /api/user 需要一个真实的后端接口；如果接口不存在，异步 setup() 会抛出错误，并由 ErrorBoundary 捕获。

---

九、嵌套 Suspense 边界

嵌套边界用于把不同区域的异步等待分开。

<template>
  <Suspense :timeout="1000">
    <template #default>
      <PageLayout>
        <template #header>
          <Header />
        </template>

        <template #main>
          <Suspense :timeout="300">
            <template #default>
              <MainReport />
            </template>

            <template #fallback>
              <MainReportSkeleton />
            </template>
          </Suspense>
        </template>
      </PageLayout>
    </template>

    <template #fallback>
      <PageSkeleton />
    </template>
  </Suspense>
</template>

可以把嵌套关系表示为：

flowchart TD
    P[父 Suspense 边界]
    P --> L[PageLayout]
    L --> H[Header]
    L --> C[子 Suspense 边界]
    C --> R[MainReport]
    P --> PF[父级 fallback: PageSkeleton]
    C --> CF[子级 fallback: MainReportSkeleton]

1. 初次渲染时

如果 Header 和 MainReport 都是第一次加载：

父边界开始等待
├── Header 完成
└── 子边界等待 MainReport
    └── MainReport 未完成

父边界仍未完成

初始阶段，父边界负责整个尚未完成的子树。子边界自己的 fallback 是否先单独展示，要结合边界创建和渲染时机判断；不能把嵌套边界理解为“所有 fallback 同时叠加”。

稳定的设计原则是：页面级父边界负责首屏骨架，已经进入页面后的局部异步刷新由子边界负责。

2. 子边界已经解析后再次等待

假设 MainReport 已经显示，之后用户切换筛选条件，新的报告数据需要异步准备：

父边界：仍然是 Resolved
子边界：从 Resolved 进入 Pending

在这种情况下，子边界可以依据自己的 timeout：

0 到 300ms：
    保留旧的 MainReport

超过 300ms：
    显示 MainReportSkeleton

子边界完成：
    显示新 MainReport

父边界不会因为子边界每次局部刷新都立即退回整页 PageSkeleton。这正是嵌套边界的价值：把故障和等待范围缩小到真正变化的区域。

3. 父边界和子边界的职责

可以按内容范围划分：

父边界：
- 首屏页面骨架
- 页面级代码和数据初始化
- 页面整体不可用时的错误界面

子边界：
- 独立面板
- 表格、图表、评论区
- 局部筛选或分页带来的异步切换

如果每一个小组件都包一个 Suspense，页面会出现过多局部 fallback，用户可能看到多个区域同时跳变。边界应与用户感知的内容单元对应，而不是机械地一组件一边界。

---

十、错误边界与嵌套边界的组合

实际应用中，经常需要让错误范围和加载范围一致：

<template>
  <ErrorBoundary>
    <Suspense :timeout="500">
      <template #default>
        <UserDashboard />
      </template>

      <template #fallback>
        <DashboardSkeleton />
      </template>
    </Suspense>
  </ErrorBoundary>
</template>

这表示：

UserDashboard 等待中
    → Suspense 显示 DashboardSkeleton

UserDashboard 抛出错误
    → ErrorBoundary 显示错误 UI

UserDashboard 成功
    → Suspense 显示真实内容

若有多个相互独立的面板，可以分别设置边界：

<template>
  <section class="dashboard">
    <ErrorBoundary>
      <Suspense>
        <template #default>
          <RevenuePanel />
        </template>

        <template #fallback>
          <RevenueSkeleton />
        </template>
      </Suspense>
    </ErrorBoundary>

    <ErrorBoundary>
      <Suspense>
        <template #default>
          <ActivityPanel />
        </template>

        <template #fallback>
          <ActivitySkeleton />
        </template>
      </Suspense>
    </ErrorBoundary>
  </section>
</template>

这样，RevenuePanel 失败不会必然让 ActivityPanel 一起进入错误状态。

---

十一、异步 setup() 中的请求取消

Suspense 会等待 Promise，但不会自动取消已经开始的网络请求。

例如，组件被卸载时，下面的请求仍可能继续：

<script setup lang="ts">
const response = await fetch('/api/user')
const user = await response.json()
</script>

对于可能快速切换的页面，可以使用 AbortController：

<script setup lang="ts">
import { onBeforeUnmount } from 'vue'

const controller = new AbortController()

onBeforeUnmount(() => {
  controller.abort()
})

const response = await fetch('/api/user', {
  signal: controller.signal
})

if (!response.ok) {
  throw new Error(`请求失败：${response.status}`)
}

const user = await response.json()
</script>

<template>
  <p>{{ user.name }}</p>
</template>

这里需要区分两种失败：

• 用户主动离开页面导致的 abort，通常不应显示“服务器错误”；
• 网络失败、HTTP 错误或数据解析失败，通常需要进入错误处理。

因此生产代码常常会单独识别：

try {
  // await fetch(...)
} catch (error) {
  if (error instanceof DOMException && error.name === 'AbortError') {
    // 组件已离开，不显示错误
  } else {
    throw error
  }
}

如果把 abort 也直接 throw 给错误边界，用户离开页面时可能看到无意义的错误日志。

---

十二、常见误解和失败表现

误解一：Suspense 会自动捕获错误

错误处理和等待处理不是同一件事。

Promise 未完成
    → Suspense 可以等待

Promise rejected
    → 进入 Vue 错误处理链路

Suspense 没有内置错误插槽。必须配置 errorComponent、onErrorCaptured 或全局错误处理器。

---

误解二：fallback 会在所有异步操作期间显示

下面的点击请求不会触发 Suspense：

async function submit() {
  await fetch('/api/submit', {
    method: 'POST'
  })
}

Suspense 管理的是组件异步依赖，不是应用中所有 Promise。交互请求应使用显式状态：

import { ref } from 'vue'

const saving = ref(false)

async function submit() {
  saving.value = true

  try {
    await fetch('/api/submit', {
      method: 'POST'
    })
  } finally {
    saving.value = false
  }
}

---

误解三：设置 timeout 就会取消慢请求

无论是异步组件的 timeout，还是 Suspense 的 timeout，都不等于网络请求取消。

• 异步组件 timeout：将组件加载标记为失败；
• Suspense timeout：控制 fallback 的显示时机；
• AbortController：才是取消 fetch 的浏览器 API。

把这三者混为一谈，会导致请求仍在后台运行，却误以为已经被终止。

---

误解四：loadingComponent 和 Suspense #fallback 会同时显示

默认 suspensible: true 的异步组件位于 Suspense 内时，等待状态由 Suspense 控制。不能期待两个加载界面自然叠加。

如果需要组件自己显示 loading：

defineAsyncComponent({
  loader: () => import('./Panel.vue'),
  loadingComponent: LoadingPanel,
  suspensible: false
})

但这样父级边界不会等待该组件。

---

误解五：异步组件失败后直接修改一个变量就能可靠重试

异步组件的加载结果可能已进入失败状态。可靠重试通常需要：

• 使用 onError 中提供的 retry()；
• 或重新创建组件实例，例如改变 key；
• 同时限制重试次数。

单纯重新设置一个与组件渲染无关的响应式变量，不一定会重新调用加载器。

---

十三、如何诊断加载、超时和错误

1. 判断是代码加载失败还是数据请求失败

代码分割失败通常发生在动态导入阶段：

loader: () => import('./Panel.vue')

常见表现包括：

• 网络面板中对应 JavaScript chunk 请求失败；
• 部署新版本后旧页面请求不到旧 chunk；
• 异步组件的 loader 直接 reject。

数据请求失败则发生在组件已经加载之后：

const response = await fetch('/api/user')

两者的处理位置不同：

动态 import 失败
    → defineAsyncComponent 的 onError / errorComponent / 错误捕获

组件内部 fetch 失败
    → async setup 的异常 / onErrorCaptured / 应用错误处理

2. 检查是否被 Suspense 接管

如果配置了 loadingComponent，但页面实际显示的是 Suspense #fallback，通常说明该异步组件仍处于 suspensible: true 状态。

可以检查：

• 异步组件是否位于 Suspense 内；
• 是否显式设置了 suspensible: false；
• fallback 是否来自父级或嵌套的子级边界。

3. 检查超时属于哪一层

页面出现错误界面前，先确认超时配置来自哪里：

defineAsyncComponent({ timeout: 8000 })
    → 异步组件自身失败

<Suspense :timeout="800">
    → 已解析边界再次等待时，延迟 fallback 切换

前者通常会走异步组件错误路径，后者只是改变视觉切换时机，不能单独证明请求失败。

4. 为全局错误处理器保留上下文

// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

app.config.errorHandler = (error, instance, info) => {
  console.error('[Vue error]', {
    error,
    instance,
    info
  })

  // 生产环境可以在这里上报错误。
}

app.mount('#app')

onErrorCaptured 适合局部错误 UI，app.config.errorHandler 适合兜底日志和监控。局部处理器返回 false 后，全局处理器可能不会再收到同一个错误，因此需要明确日志策略。

---

十四、版本和能力边界

本文基于 Vue 3、Composition API、TypeScript 和现代 Vite 工具链。

需要特别注意：

1. Suspense 在 Vue 3 文档中仍属于实验性能力，虽然已广泛用于 Vue 3 应用，但其细节和边界行为应以当前项目使用的 Vue 版本文档为准。
2. <script setup> 顶层 await 是 Vue 3 的能力，但必须处在支持异步依赖管理的组件上下文中，通常需要 Suspense 祖先。
3. defineAsyncComponent、suspensible、timeout、onError 属于 Vue 3 异步组件 API；不同小版本不应在未核对文档的情况下假定所有边界行为完全一致。
4. Vite 的动态导入会影响 chunk 拆分和部署结果，但 chunk 文件命名、缓存策略和错误形式属于构建工具与部署系统的实现细节，不是 Vue Suspense 的规范保证。

---

十五、把整个机制压缩成一条状态链

异步组件与 Suspense 的职责可以最后归纳为两条并行状态机。

异步组件：

未加载
  ↓
loader 执行
  ├── 成功 → 组件可渲染
  ├── 失败 → onError
  │           ├── retry → 再次 loader
  │           └── fail → errorComponent / 错误捕获
  └── 超时 → 失败路径

Suspense 边界：

首次 Pending
  ↓
显示 fallback
  ↓
所有异步依赖完成
  ↓
Resolved，显示 default

Resolved 后再次出现异步依赖
  ↓
保留旧内容
  ↓ timeout 到期
显示 fallback
  ↓
新依赖完成
  ↓
显示新内容

二者最重要的分工是：

• defineAsyncComponent 管理“组件定义如何加载、失败后如何重试”；
• Suspense 管理“异步组件树何时整体可显示、等待期间显示什么”；
• onErrorCaptured 管理“失败后由哪一层展示错误并决定是否继续传播”；
• AbortController 管理“已经开始的网络请求是否取消”。

理解这四个职责边界后，加载、错误、超时和嵌套边界就不再是互相重叠的配置项，而是分别作用于组件加载、组件树协调、错误传播和请求生命周期的不同机制。

---

系列导航与关联阅读

• 系列入口：Vue 完整学习路线：从响应式与组件到工程化、SSR 和生产交付
• 上一篇：Vue Transition 与 TransitionGroup：进入离开、列表动画和性能
• 下一篇：Vue KeepAlive 深入：缓存键、include、生命周期和内存治理

官方资料

• Vue.js Guide
• Vue.js API Reference

本文依据 Vue、Vite 与生态项目官方文档重新梳理；正文与示例由 WR BLOG 编写。