异步组件与 Suspense | Async Components and Suspense in Vue 3

本文档对标 MIT 6.170、Stanford CS142、CMU 17-437 软件工程课程水准，系统化阐述 Vue 3 异步组件（defineAsyncComponent）与 Suspense 机制的原理、形式化定义、企业级实践与对比分析。涵盖代码分割（Code Splitting）、动态导入（Dynamic Import）、异步依赖编排（Async Orchestration）、错误边界（Error Boundary）、加载状态管理、SSR 流式渲染等主题，并辅以数学建模、对比分析、案例研究与习题。

目录

1. 学习目标
2. 历史动机与发展脉络
3. 形式化定义
4. 理论推导与原理解析
5. 代码示例
6. 对比分析
7. 常见陷阱与最佳实践
8. 工程实践
9. 案例研究
10. 习题
11. 参考文献
12. 延伸阅读

1. 学习目标 | Learning Objectives

本章节基于 Bloom 教育目标分类法设计学习目标，覆盖记忆、理解、应用、分析、评价、创造六个层次。完成本章学习后，学习者应能够独立设计企业级异步加载架构，并对其性能特性与边界条件做出准确判断。

1.1 记忆层（Remember）

• R1：准确陈述 defineAsyncComponent 的函数签名，包括简单形式 defineAsyncComponent(loader) 与完整配置形式 defineAsyncComponent(options)。
• R2：列举异步组件的完整配置项：loader、loadingComponent、errorComponent、delay、timeout、suspensible、onError。
• R3：复述 Suspense 组件的两个具名插槽：#default（默认内容）与 #fallback（加载占位）。
• R4：背记 Suspense 的事件回调：onPending（pending）、onResolve（resolve）、onFallback（fallback）。
• R5：识别 async setup() 必须在 Suspense 内使用，否则 Vue 会抛出警告。

1.2 理解层（Understand）

• U1：解释代码分割（Code Splitting）的核心思想：将应用拆分为多个 chunk，按需加载，减少首屏体积。
• U2：阐述动态导入（Dynamic Import）import('./Component.vue') 返回 Promise 的语法，以及 Webpack/Vite 如何将其转换为独立 chunk。
• U3：描述 Suspense 的工作原理：等待所有异步依赖完成后，再渲染默认插槽；若任一依赖 pending，则渲染 fallback。
• U4：理解 defineAsyncComponent 与 Suspense 的协作模式：suspensible: true（默认）时，异步组件参与 Suspense 协调；suspensible: false 时，异步组件独立管理 loading/error 状态。
• U5：说明 delay 与 timeout 的语义：delay 防止 loading 闪烁，timeout 触发超时错误，避免无限等待。

1.3 应用层（Apply）

• A1：使用 defineAsyncComponent 实现路由懒加载，将每个路由对应的组件拆分为独立 chunk。
• A2：使用 Suspense 包装异步组件树，统一管理加载占位与错误边界。
• A3：实现一个带重试机制的异步组件，使用 onError 回调实现最多 3 次重试。
• A4：在 async setup() 中调用 API 获取数据，配合 Suspense 实现加载态管理。
• A5：使用 Vite 的 import.meta.glob 实现批量异步加载，构建可配置的组件注册表。

1.4 分析层（Analyze）

• An1：分析 Suspense 的依赖收集机制：Vue 内部维护异步依赖计数器，每个异步 setup 注册依赖，完成时递减，归零时触发 resolve。
• An2：对比 Vue Suspense 与 React Suspense 的实现差异：Vue 基于组件树依赖追踪，React 基于 throw Promise 模式。
• An3：解构 defineAsyncComponent 的内部状态机：idle → loading → loaded/error，分析状态转换条件。
• An4：分析异步组件在 SSR 中的行为：服务端同步等待所有异步依赖，客户端 hydration 时跳过加载态。
• An5：评估 delay: 200ms 与 delay: 0 在用户体验上的差异：前者避免闪烁，后者立即显示 loading。

1.5 评价层（Evaluate）

• E1：评估一个路由是否应当懒加载，权衡首屏体积、加载延迟、SEO 影响。
• E2：判断何时应当使用 Suspense 包裹异步组件，何时使用 defineAsyncComponent 的内置 loading/error 配置，权衡灵活性。
• E3：评价 async setup() 的适用场景：何时优于 onMounted + 状态管理，何时引入过度复杂。
• E4：权衡 Suspense 在大型应用中的使用成本：嵌套 Suspense、错误边界、加载顺序的复杂性。

1.6 创造层（Create）

• C1：设计一套企业级异步组件加载策略，支持优先级、预加载、降级、缓存，并与 Vue Router 深度集成。
• C2：构建一个基于 Suspense 的流式 SSR 框架，支持服务端流式渲染与客户端渐进式 hydration。
• C3：实现一个异步组件的错误恢复系统，支持自动重试、降级组件、用户手动重试、错误上报。
• C4：设计一个可视化的异步依赖分析工具，展示组件树的异步加载链路、加载时间、错误率，辅助性能优化。

2. 历史动机与发展脉络 | Historical Motivation and Evolution

2.1 代码分割的起源

Web 应用的体积随功能增长而膨胀，首屏 JS 体积从 2010 年的几十 KB 增长到 2025 年的数 MB。代码分割（Code Splitting）是应对此问题的核心技术，其设计动机：

1. 首屏性能：用户访问页面时只需加载首屏所需的 JS，减少 LCP（Largest Contentful Paint）时间。
2. 带宽节省：移动用户按需加载，避免下载未访问页面的代码。
3. 缓存优化：将稳定代码与频繁变化代码分离，提升缓存命中率。

关键里程碑：

2.2 Vue 2 时代的异步组件

Vue 2 提供 defineAsyncComponent（早期为 () => Promise），支持基础代码分割：

// Vue 2 异步组件
Vue.component('async-component', (resolve, reject) => {
  import('./AsyncComponent.vue').then(resolve).catch(reject);
});

// Vue 2.5+ 工厂函数形式
const AsyncComponent = () => import('./AsyncComponent.vue');

Vue 2 异步组件的限制：

• 无内置 loading/error 配置，需手动管理。
• 无超时机制，组件加载失败时无降级方案。
• 无 Suspense 协调，多个异步组件无法统一管理加载态。
• 无 async setup()，数据获取需在 created 或 mounted 中处理。

2.3 Vue 3 时代（2020-至今）：完整重构

Vue 3 对异步组件进行根本性重构，并引入 Suspense：

2.3.1 defineAsyncComponent 完整配置（Vue 3.0）

import { defineAsyncComponent } from 'vue';

const AsyncComp = defineAsyncComponent({
  loader: () => import('./HeavyComponent.vue'),
  loadingComponent: LoadingSpinner,
  errorComponent: ErrorDisplay,
  delay: 200,           // 延迟显示 loading（毫秒）
  timeout: 3000,        // 超时显示 error（毫秒）
  suspensible: true,    // 参与 Suspense 协调（默认 true）
  onError(error, retry, fail, attempts) {
    if (attempts <= 3) retry();
    else fail();
  },
});

2.3.2 Suspense 组件（Vue 3.0，实验性）

<Suspense>
  <template #default>
    <AsyncComponent />
  </template>
  <template #fallback>
    <LoadingSpinner />
  </template>
</Suspense>

2.3.3 async setup()（Vue 3.0）

Vue 3 允许 setup 为 async 函数，自动与 Suspense 集成：

export default {
  async setup() {
    const data = await fetch('/api/data').then(r => r.json());
    return { data };
  },
};

2.3.4 嵌套 Suspense（Vue 3.2+）

Vue 3.2+ 支持嵌套 Suspense，允许局部异步依赖独立管理加载态：

<Suspense>
  <template #default>
    <Header />
    <Suspense>
      <template #default>
        <MainContent />
      </template>
      <template #fallback>
        <MainSkeleton />
      </template>
    </Suspense>
  </template>
  <template #fallback>
    <PageSkeleton />
  </template>
</Suspense>

2.3.5 SSR 流式渲染（Vue 3.3+）

Vue 3.3+ 优化了 SSR 中的 Suspense，支持流式渲染（renderToNodeStream），服务端在异步依赖完成时立即输出对应 HTML，提升首屏 TTFB（Time To First Byte）。

2.4 Evan You 的设计哲学

Evan You 对异步组件与 Suspense 的定位：

1. 声明式优于命令式：通过 Suspense 组件声明加载占位，而非手动切换 v-if 状态。
2. 渐进式复杂度：简单场景用 defineAsyncComponent 内置配置，复杂场景用 Suspense 协调多个异步依赖。
3. 与 React Suspense 互补：借鉴 React 的概念，但实现基于 Vue 的响应式系统，重渲染粒度更细。
4. 实验性优先级：Suspense 长期标记为实验性，API 可能调整，避免过早稳定化限制演进。

2.5 与 React.lazy/Suspense 的对比

React 16.6（2018）引入 React.lazy 与 Suspense，与 Vue 方案解决相似问题：

关键差异：

• Vue 的 defineAsyncComponent 内置 loading/error/timeout/重试，配置更完整。
• React 的 lazy 更精简，复杂场景需配合 ErrorBoundary 与外部数据获取库。
• Vue 的 async setup() 允许组件级数据获取与 Suspense 集成，React 需借助 React Query 等。

2.6 与 Solid.js、Svelte 的对比

Solid.js 的 lazy 与 Vue 最相似，但基于细粒度响应式，性能更优。Svelte 依赖编译时优化，运行时 Suspense 较弱。Angular 的 loadChildren 仅在路由层支持异步。

3. 形式化定义 | Formal Definitions

3.1 异步组件的形式化定义

定义 3.1（异步组件）：异步组件是一个返回 Promise 的工厂函数，记为 $A$：

Promise resolve 时返回组件定义对象，reject 时表示加载失败。

定义 3.2（defineAsyncComponent）：defineAsyncComponent 将异步工厂转换为同步可渲染的包装组件：

包装组件内部维护状态机：

3.2 异步组件配置的形式化

定义 3.3（完整配置）：defineAsyncComponent 的完整配置是一个七元组：

其中：

• $\text{loader}: () \to \text{Promise<Component>}$：加载函数。
• $\text{loadingComponent}: \text{Component}$：加载占位组件。
• $\text{errorComponent}: \text{Component}$：错误降级组件。
• $\text{delay}: \mathbb{N} \text{ (ms)}$：延迟显示 loading，默认 200ms。
• $\text{timeout}: \mathbb{N} \text{ (ms)}$：超时阈值，默认 Infinity。
• $\text{suspensible}: \text{boolean}$：是否参与 Suspense 协调，默认 true。
• $\text{onError}: (\text{error}, \text{retry}, \text{fail}, \text{attempts}) \to \text{void}$：错误回调。

3.3 状态机的形式化

定义 3.4（状态转换）：异步组件包装器的状态转换：

关键性质：

• loaded 是吸收态，组件加载成功后不再重新加载（除非组件被卸载并重新挂载）。
• error 可通过 retry 转回 loading，支持错误恢复。
• timeout 与 loader.reject 都会触发 error，但 timeout 不取消 loader。

3.4 Suspense 的形式化定义

定义 3.5（Suspense 依赖）：Suspense 维护一个异步依赖集合 $D$：

每个 $d_i$ 是一个异步依赖（来自 async setup() 或 suspensible: true 的异步组件）。

定义 3.6（Suspense 状态）：Suspense 的状态由依赖集合决定：

渲染规则：

• $\text{pending}$：渲染 #fallback 插槽。
• $\text{resolved}$：渲染 #default 插槽。
• $\text{rejected}$：向上抛出错误，由 ErrorBoundary 或上层 Suspense 处理。

3.5 async setup() 的形式化

定义 3.7（async setup）：async setup() 是返回 Promise 的 setup 函数：

其中 $\text{Bindings}$ 是模板可访问的响应式对象集合。

Suspense 集成：在 Suspense 内使用 async setup 时，Vue 自动将该 Promise 注册为依赖：

Promise resolve 时递减依赖计数，归零时触发 Suspense resolve。

3.6 代码分割的形式化

定义 3.8（chunk 分割）：设应用总代码量为 $C$，分割为 $n$ 个 chunk：

首屏加载量为 $c_{\text{initial}} \subseteq C$，按需加载量为 $c_{\text{lazy}} = C \setminus c_{\text{initial}}$。

目标：最小化首屏加载量 $|c_{\text{initial}}|$，同时控制总加载量 $|C|$。

约束：

• 用户访问路由 $r$ 时，必须加载 $c_r$（该路由的组件）。
• 共享依赖（如 Vue 运行时）应抽离为 vendor chunk，避免重复。

3.7 动态导入的形式化

定义 3.9（动态导入）：import('./module') 返回一个 Promise：

Webpack/Vite 将其转换为：

1. chunk 创建：构建时将 module 拆分为独立文件。
2. 运行时加载：通过 <script> 标签或 fetch 加载 chunk。
3. 模块缓存：加载后缓存到全局，重复 import() 返回同一 Promise。

复杂度：

• 首次加载：$O(|c|)$，需下载并解析整个 chunk。
• 后续加载：$O(1)$，从缓存读取。

4. 理论推导与原理解析 | Theoretical Derivation

4.1 defineAsyncComponent 的内部实现

Vue 3 的 defineAsyncComponent 内部实现是一个包装组件，维护状态机：

// Vue 3 内部实现（简化）
export function defineAsyncComponent(options) {
  if (typeof options === 'function') {
    options = { loader: options };
  }
  
  const { loader, loadingComponent, errorComponent, delay = 200, timeout, suspensible = true, onError } = options;
  
  let resolvedComponent = null;
  let loading = false;
  let error = null;
  let loaded = false;
  let retries = 0;
  
  return defineComponent({
    name: 'AsyncComponentWrapper',
    async setup() {
      // 如果已加载，直接返回
      if (loaded) {
        return { component: resolvedComponent };
      }
      
      // 加载组件
      const load = () => {
        if (loading) return;
        loading = true;
        error = null;
        
        const promise = loader()
          .then(c => {
            resolvedComponent = c.__esModule ? c.default : c;
            loaded = true;
          })
          .catch(err => {
            error = err;
            if (onError) {
              onError(err, () => {
                retries++;
                load();
              }, () => {}, retries);
            }
          });
        
        // 超时处理
        if (timeout) {
          setTimeout(() => {
            if (!loaded && !error) {
              error = new Error(`Async component timed out after ${timeout}ms`);
            }
          }, timeout);
        }
        
        return promise;
      };
      
      await load();
      
      return () => {
        if (loaded) return h(resolvedComponent);
        if (error && errorComponent) return h(errorComponent, { error });
        if (loading && loadingComponent) return h(loadingComponent);
        return null;
      };
    },
  });
}

关键点：

1. 缓存机制：loaded 与 resolvedComponent 在模块作用域缓存，重复挂载不重新加载。
2. 重试支持：onError 提供 retry 回调，递归调用 load。
3. 状态机：loading/loaded/error 三态切换，驱动渲染。

4.2 Suspense 的依赖追踪机制

Suspense 内部维护一个 deps 集合与计数器：

// Vue 3 内部实现（简化）
const Suspense = {
  name: 'Suspense',
  setup(props, { slots }) {
    const suspense = {
      deps: 0,            // 待解决的依赖数
      pending: false,
      fallback: false,
      effects: [],
      resolve() {
        this.deps--;
        if (this.deps === 0) {
          this.pending = false;
          this.fallback = false;
          // 触发渲染默认插槽
        }
      },
      reject() {
        this.pending = false;
        // 向上抛出错误
      },
      register(dep) {
        this.deps++;
        this.pending = true;
        this.fallback = true;
        dep.then(this.resolve.bind(this)).catch(this.reject.bind(this));
      },
    };
    
    return () => {
      if (suspense.fallback) {
        return slots.fallback?.();
      }
      return slots.default?.();
    };
  },
};

依赖注册流程：

1. async setup 触发：async setup() 返回 Promise，Vue 将其注册到最近的 Suspense。
2. 递增计数器：suspense.deps++，suspense.pending = true。
3. Promise 链接：Promise resolve 时调用 resolve()，递减计数器。
4. 归零触发渲染：deps === 0 时切换到默认插槽。

4.3 async setup() 的执行流程

async setup() 的执行流程：

1. setup 调用：Vue 调用 setup()，返回 Promise。
2. Suspense 注册：Vue 将 Promise 注册到当前 Suspense。
3. fallback 渲染：Suspense 渲染 #fallback 插槽。
4. Promise resolve：异步操作完成，setup 返回 bindings。
5. Suspense resolve：递减依赖计数，归零时切换到 #default。
6. 默认插槽渲染：渲染组件，使用 setup 返回的 bindings。

关键点：

• async setup() 中抛出的错误会被 Suspense 捕获，向上传播。
• 多个 async setup() 嵌套时，Suspense 等待所有依赖完成。
• async setup() 中可以使用 onMounted 等生命周期钩子，但需在 Promise resolve 后执行。

4.4 代码分割的性能分析

首屏加载量优化：

设应用总代码量为 $C$，首屏路由代码量为 $c_r$，公共依赖为 $v$。

• 无代码分割：首屏加载 $C$，包含所有路由代码。
• 有代码分割：首屏加载 $v + c_r$，其余路由按需加载。

收益：

若 $C = 2\text{MB}$，$v = 200\text{KB}$，$c_r = 300\text{KB}$，则：

代价：

• 路由切换时需加载新 chunk，增加延迟。
• HTTP 请求数增多，需 HTTP/2 或预加载优化。

4.5 chunk 预加载策略

Vite/Webpack 提供多种预加载策略：

1. <link rel="modulepreload">：Vite 默认为动态导入添加 modulepreload，并行加载 chunk。
2. webpackPrefetch：Webpack 4+ 支持在 import 注释中声明 prefetch。

import(/* webpackPrefetch: true */ './module');

3. 手动预加载：在用户 hover 链接时预加载对应 chunk。

link.addEventListener('mouseenter', () => {
  import('./route-component');
});

预加载的复杂度分析：

• 带宽成本：$O(|c|)$，每个预加载消耗带宽。
• 性能收益：用户实际访问时 $O(1)$，从缓存读取。
• 权衡：仅预加载高概率访问的 chunk。

4.6 Suspense 嵌套的复杂度

嵌套 Suspense 允许局部依赖独立管理：

<Suspense> (外层)
  <Header />
  <Suspense> (内层)
    <MainContent />
  </Suspense>
</Suspense>

渲染顺序：

1. 外层 Suspense 等待所有依赖（包括 Header 与内层 Suspense）。
2. 内层 Suspense 独立等待 MainContent。
3. 内层 resolve 后，外层 deps 递减；外层 deps 归零时整体 resolve。

复杂度：

• 依赖追踪：$O(n)$，$n$ 为 Suspense 节点数。
• 错误传播：内层错误可被外层捕获，也可独立处理。

4.7 与 React Suspense 的原理对比

React 18 的 Suspense 基于 throw Promise 模式：

// React 内部（简化）
function Suspense({ fallback, children }) {
  try {
    return children;
  } catch (promise) {
    if (promise instanceof Promise) {
      promise.then(() => rerender());
      return fallback;
    }
    throw promise;
  }
}

// 数据获取库使用 throw
function use(fetchPromise) {
  if (fetchPromise.pending) throw fetchPromise;
  return fetchPromise.result;
}

Vue 的优势：

• 显式依赖注册：async setup() 自动注册，无需 throw。
• 响应式追踪：Vue 的响应式系统天然支持依赖追踪。
• 性能更优：避免 throw 的栈展开开销。

React 的优势：

• 通用性：任意数据获取库（如 React Query）可通过 throw 集成。
• 并发渲染：React 18 的 Concurrent Rendering 与 Suspense 深度集成。

4.8 SSR 流式渲染的原理

Vue 3.3+ 的 SSR 支持 Suspense 流式渲染：

import { renderToNodeStream } from 'vue/server-renderer';

const stream = renderToNodeStream(app);
stream.pipe(res);

流程：

1. 同步部分输出：非异步依赖立即输出 HTML。
2. 异步依赖 pending：输出占位注释 <!-- suspense-pending -->。
3. 异步依赖 resolve：流式输出对应 HTML，替换占位。
4. 完成：所有依赖 resolve，输出闭合标签。

性能收益：

• TTFB（Time To First Byte）显著降低：服务端无需等待所有数据即可响应。
• 用户感知性能提升：浏览器逐步渲染，无需等待完整 HTML。

4.9 错误传播与捕获

Suspense 的错误传播规则：

1. async setup 抛出错误：Promise reject，Suspense 进入 rejected 状态。
2. 向上传播：错误向上冒泡，寻找 ErrorBoundary 或上层 Suspense 的 onError。
3. 未捕获错误：若未捕获，Vue 在控制台警告并渲染空内容。

ErrorBoundary 模式：

Vue 3 没有官方 ErrorBoundary 组件，但可通过 onErrorCaptured 钩子实现：

export default {
  setup(props, { slots }) {
    const error = ref(null);
    
    onErrorCaptured((err) => {
      error.value = err;
      return false; // 阻止错误继续传播
    });
    
    return () => {
      if (error.value) {
        return h(ErrorDisplay, { error: error.value, onRetry: () => error.value = null });
      }
      return slots.default?.();
    };
  },
};

5. 代码示例 | Code Examples

5.1 基础用法：路由懒加载

// router/index.ts —— Vue 3.4+ + Vue Router 4
import { createRouter, createWebHistory } from 'vue-router';
import Home from '../views/Home.vue'; // 首屏直接 import

const routes = [
  {
    path: '/',
    component: Home,
  },
  {
    path: '/about',
    // 异步加载 About 组件
    component: () => import('../views/About.vue'),
  },
  {
    path: '/dashboard',
    // 命名 chunk，便于分析与缓存
    component: () => import(/* webpackChunkName: "dashboard" */ '../views/Dashboard.vue'),
  },
  {
    path: '/settings',
    // Vite 风格的注释
    component: () => import('../views/Settings.vue'),
  },
];

export const router = createRouter({
  history: createWebHistory(),
  routes,
});

5.2 完整配置：defineAsyncComponent

<!-- AsyncComponent.vue —— Vue 3.4+ -->
<script setup>
import { defineAsyncComponent } from 'vue';
import LoadingSpinner from './LoadingSpinner.vue';
import ErrorDisplay from './ErrorDisplay.vue';

// 完整配置的异步组件
const HeavyChart = defineAsyncComponent({
  loader: () => import('./HeavyChart.vue'),
  loadingComponent: LoadingSpinner,
  errorComponent: ErrorDisplay,
  delay: 200,           // 延迟 200ms 显示 loading，避免闪烁
  timeout: 10000,       // 10 秒超时
  suspensible: true,    // 参与 Suspense 协调
  onError(error, retry, fail, attempts) {
    // 最多重试 3 次
    if (attempts <= 3) {
      console.warn(`Loading failed, retrying (${attempts}/3)...`, error);
      retry();
    } else {
      console.error('Max retries reached, giving up.', error);
      fail();
    }
  },
});
</script>

<template>
  <div class="container">
    <h2>Dashboard</h2>
    <HeavyChart :data="chartData" />
  </div>
</template>

5.3 Suspense 基础用法

<!-- AsyncPage.vue -->
<script setup>
import { defineAsyncComponent } from 'vue';

const AsyncHeader = defineAsyncComponent(() => import('./Header.vue'));
const AsyncContent = defineAsyncComponent(() => import('./Content.vue'));
const AsyncFooter = defineAsyncComponent(() => import('./Footer.vue'));
</script>

<template>
  <Suspense>
    <template #default>
      <div class="page">
        <AsyncHeader />
        <AsyncContent />
        <AsyncFooter />
      </div>
    </template>
    <template #fallback>
      <div class="loading">
        <LoadingSpinner size="large" />
        <p>Loading page...</p>
      </div>
    </template>
  </Suspense>
</template>

<style scoped>
.loading {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  height: 100vh;
  gap: 16px;
}
</style>

5.4 async setup() 与数据获取

<!-- UserProfile.vue -->
<script setup>
import { ref } from 'vue';

// async setup：Suspense 等待此 Promise
const user = ref(null);
const posts = ref([]);

// 并行获取用户信息与文章
async function fetchData() {
  const [userResponse, postsResponse] = await Promise.all([
    fetch('/api/user/1').then(r => r.json()),
    fetch('/api/posts?userId=1').then(r => r.json()),
  ]);
  user.value = userResponse;
  posts.value = postsResponse;
}

// setup 是 async 的
await fetchData();
</script>

<template>
  <div class="user-profile">
    <h1>{{ user.name }}</h1>
    <p>{{ user.email }}</p>
    <h2>Posts</h2>
    <ul>
      <li v-for="post in posts" :key="post.id">{{ post.title }}</li>
    </ul>
  </div>
</template>

<!-- App.vue —— 使用 Suspense 包裹 async setup 组件 -->
<script setup>
import UserProfile from './UserProfile.vue';
import LoadingSkeleton from './LoadingSkeleton.vue';
import { onErrorCaptured, ref } from 'vue';

const error = ref(null);

onErrorCaptured((err) => {
  error.value = err.message;
  return false; // 阻止错误继续传播
});
</script>

<template>
  <div v-if="error" class="error">
    <h2>Something went wrong</h2>
    <p>{{ error }}</p>
    <button @click="error = null">Retry</button>
  </div>
  
  <Suspense v-else>
    <template #default>
      <UserProfile />
    </template>
    <template #fallback>
      <LoadingSkeleton />
    </template>
  </Suspense>
</template>

5.5 嵌套 Suspense

<!-- NestedSuspense.vue -->
<script setup>
import { defineAsyncComponent } from 'vue';

const AsyncHeader = defineAsyncComponent(() => import('./Header.vue'));
const AsyncSidebar = defineAsyncComponent(() => import('./Sidebar.vue'));
const AsyncMain = defineAsyncComponent(() => import('./MainContent.vue'));
const AsyncComments = defineAsyncComponent(() => import('./Comments.vue'));
</script>

<template>
  <!-- 外层 Suspense：等待 Header 与 Sidebar -->
  <Suspense>
    <template #default>
      <div class="layout">
        <AsyncHeader />
        <div class="body">
          <AsyncSidebar />
          
          <!-- 内层 Suspense：等待 Main 与 Comments -->
          <main class="main">
            <Suspense>
              <template #default>
                <div>
                  <AsyncMain />
                  <AsyncComments />
                </div>
              </template>
              <template #fallback>
                <div class="main-skeleton">
                  <SkeletonLine />
                  <SkeletonLine />
                  <SkeletonLine />
                </div>
              </template>
            </Suspense>
          </main>
        </div>
      </div>
    </template>
    <template #fallback>
      <div class="page-skeleton">
        <SkeletonBlock height="60px" />
        <SkeletonBlock height="400px" />
      </div>
    </template>
  </Suspense>
</template>

5.6 Suspense 事件

<!-- SuspenseWithEvents.vue -->
<script setup>
import { ref, defineAsyncComponent } from 'vue';

const AsyncComp = defineAsyncComponent(() => import('./AsyncComp.vue'));

const status = ref('resolved');
const events = ref([]);

function onPending() {
  status.value = 'pending';
  events.value.push('pending at ' + new Date().toISOString());
  console.log('Suspense: pending');
}

function onResolve() {
  status.value = 'resolved';
  events.value.push('resolve at ' + new Date().toISOString());
  console.log('Suspense: resolved');
}

function onFallback() {
  status.value = 'fallback';
  events.value.push('fallback at ' + new Date().toISOString());
  console.log('Suspense: fallback');
}
</script>

<template>
  <div>
    <p>Status: {{ status }}</p>
    <Suspense @pending="onPending" @resolve="onResolve" @fallback="onFallback">
      <template #default>
        <AsyncComp />
      </template>
      <template #fallback>
        <LoadingSpinner />
      </template>
    </Suspense>
    
    <details>
      <summary>Events Log</summary>
      <ul>
        <li v-for="event in events" :key="event">{{ event }}</li>
      </ul>
    </details>
  </div>
</template>

5.7 错误处理与重试

<!-- AsyncWithErrorHandling.vue -->
<script setup>
import { defineAsyncComponent, ref, onErrorCaptured } from 'vue';

const retryCount = ref(0);
const maxRetries = 3;
const hasError = ref(false);

// 带重试机制的异步组件
const createAsyncComponent = () => defineAsyncComponent({
  loader: () => import('./UnstableComponent.vue'),
  loadingComponent: { template: '<div>Loading...</div>' },
  errorComponent: { template: '<div>Failed to load</div>' },
  delay: 200,
  timeout: 5000,
  onError(err, retry, fail, attempts) {
    retryCount.value = attempts;
    if (attempts <= maxRetries) {
      console.warn(`Attempt ${attempts} failed, retrying...`, err);
      setTimeout(retry, 1000 * attempts); // 指数退避
    } else {
      hasError.value = true;
      fail();
    }
  },
});

const AsyncComp = createAsyncComponent();

// 错误边界
onErrorCaptured((err, instance, info) => {
  console.error('Error captured:', err, info);
  hasError.value = true;
  return false; // 阻止错误传播
});

function reload() {
  hasError.value = false;
  retryCount.value = 0;
  // 强制重新加载组件
  location.reload();
}
</script>

<template>
  <div>
    <div v-if="hasError" class="error-boundary">
      <h2>Failed to load component</h2>
      <p>Retried {{ retryCount }} times.</p>
      <button @click="reload">Reload Page</button>
    </div>
    
    <Suspense v-else>
      <template #default>
        <AsyncComp />
      </template>
      <template #fallback>
        <div class="loading">
          <LoadingSpinner />
          <p v-if="retryCount > 0">Retrying... ({{ retryCount }}/{{ maxRetries }})</p>
        </div>
      </template>
    </Suspense>
  </div>
</template>

<style scoped>
.error-boundary {
  padding: 24px;
  background: #fee;
  border: 1px solid #f88;
  border-radius: 4px;
  text-align: center;
}
.error-boundary button {
  margin-top: 12px;
  padding: 8px 16px;
  background: #f66;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}
</style>

5.8 Vite 批量异步加载

// utils/loadComponents.js —— Vue 3.4+ + Vite 5
import { defineAsyncComponent } from 'vue';

/**
 * 批量异步加载组件
 * @param {string} glob - glob 模式，如 './components/*.vue'
 * @returns {Object} 组件映射表
 */
export function loadComponents(glob) {
  const modules = import.meta.glob(glob);
  const components = {};
  
  for (const [path, loader] of Object.entries(modules)) {
    // 从路径提取组件名：./components/UserCard.vue -> UserCard
    const name = path.match(/\/([^/]+)\.vue$/)[1];
    components[name] = defineAsyncComponent({
      loader,
      loadingComponent: () => import('./LoadingSpinner.vue'),
      errorComponent: () => import('./ErrorDisplay.vue'),
      delay: 200,
    });
  }
  
  return components;
}

// 使用
const components = loadComponents('./components/*.vue');
// 注册全局
for (const [name, component] of Object.entries(components)) {
  // app.component(name, component);
}

5.9 预加载策略

// utils/preload.js
const preloaded = new Set();

/**
 * 预加载路由组件
 * @param {string} routeName - 路由名称
 */
export async function preloadRoute(routeName) {
  if (preloaded.has(routeName)) return;
  preloaded.add(routeName);
  
  const route = router.getRoutes().find(r => r.name === routeName);
  if (route && typeof route.component === 'function') {
    await route.component();
  }
}

// 在导航栏 hover 时预加载
document.querySelectorAll('a[href]').forEach(link => {
  link.addEventListener('mouseenter', () => {
    const route = link.getAttribute('href');
    const matched = router.resolve(route);
    if (matched.name) {
      preloadRoute(matched.name);
    }
  }, { once: true });
});

// 在空闲时预加载关键路由
if ('requestIdleCallback' in window) {
  requestIdleCallback(() => {
    preloadRoute('dashboard');
    preloadRoute('profile');
  });
} else {
  setTimeout(() => {
    preloadRoute('dashboard');
    preloadRoute('profile');
  }, 3000);
}

5.10 组件加载状态可视化

<!-- AsyncLoader.vue —— 可视化加载状态 -->
<script setup>
import { defineAsyncComponent, ref, computed } from 'vue';

const props = defineProps({
  loader: { type: Function, required: true },
  delay: { type: Number, default: 200 },
  timeout: { type: Number, default: 10000 },
});

const state = ref('idle'); // idle, loading, loaded, error
const loadingTime = ref(0);
const error = ref(null);
let timer = null;
let startTime = 0;

const AsyncComponent = defineAsyncComponent({
  loader: props.loader,
  loadingComponent: {
    setup() {
      return () => null; // 由外层控制 loading UI
    },
  },
  delay: props.delay,
  timeout: props.timeout,
  onError(err, retry, fail, attempts) {
    error.value = err;
    state.value = 'error';
  },
});

const progress = computed(() => {
  if (state.value === 'loaded') return 100;
  if (state.value === 'loading') {
    return Math.min(90, (loadingTime.value / props.timeout) * 100);
  }
  return 0;
});

function startLoading() {
  state.value = 'loading';
  startTime = Date.now();
  timer = setInterval(() => {
    loadingTime.value = Date.now() - startTime;
  }, 100);
}

function stopLoading() {
  clearInterval(timer);
  state.value = 'loaded';
}

// 监听加载完成
// 实际实现需更复杂，此处示意
</script>

<template>
  <div class="async-loader">
    <div v-if="state === 'loading'" class="loading">
      <div class="progress-bar">
        <div class="progress" :style="{ width: progress + '%' }"></div>
      </div>
      <p>Loading... {{ loadingTime }}ms</p>
    </div>
    
    <div v-else-if="state === 'error'" class="error">
      <p>Failed to load: {{ error?.message }}</p>
      <button @click="$emit('retry')">Retry</button>
    </div>
    
    <Suspense @pending="startLoading" @resolve="stopLoading">
      <template #default>
        <AsyncComponent />
      </template>
    </Suspense>
  </div>
</template>

<style scoped>
.async-loader {
  position: relative;
}
.progress-bar {
  width: 100%;
  height: 4px;
  background: #eee;
  border-radius: 2px;
  overflow: hidden;
}
.progress {
  height: 100%;
  background: #007bff;
  transition: width 0.1s;
}
</style>

5.11 企业级异步组件注册器

// utils/asyncComponents.ts —— 企业级异步组件注册
import { defineAsyncComponent, type Component } from 'vue';
import LoadingSpinner from '@/components/LoadingSpinner.vue';
import ErrorDisplay from '@/components/ErrorDisplay.vue';

interface AsyncComponentOptions {
  loader: () => Promise<{ default: Component } | Component>;
  delay?: number;
  timeout?: number;
  retries?: number;
  retryDelay?: number;
}

const defaultLoading = LoadingSpinner;
const defaultError = ErrorDisplay;

export function createAsyncComponent(options: AsyncComponentOptions) {
  const {
    loader,
    delay = 200,
    timeout = 10000,
    retries = 3,
    retryDelay = 1000,
  } = options;
  
  let attempts = 0;
  
  return defineAsyncComponent({
    loader,
    loadingComponent: defaultLoading,
    errorComponent: defaultError,
    delay,
    timeout,
    onError(err, retry, fail) {
      attempts++;
      if (attempts <= retries) {
        console.warn(
          `[AsyncComponent] Loading failed (attempt ${attempts}/${retries})`,
          err
        );
        setTimeout(retry, retryDelay * attempts); // 指数退避
      } else {
        console.error('[AsyncComponent] Max retries reached', err);
        fail();
      }
    },
  });
}

// 集中注册所有异步组件
export function registerAsyncComponents(app) {
  const components = {
    'HeavyChart': () => import('@/components/HeavyChart.vue'),
    'MarkdownEditor': () => import('@/components/MarkdownEditor.vue'),
    'CodeBlock': () => import('@/components/CodeBlock.vue'),
    'DataGrid': () => import('@/components/DataGrid.vue'),
    'RichTextEditor': () => import('@/components/RichTextEditor.vue'),
  };
  
  for (const [name, loader] of Object.entries(components)) {
    app.component(name, createAsyncComponent({ loader }));
  }
}

// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import { registerAsyncComponents } from './utils/asyncComponents';

const app = createApp(App);
registerAsyncComponents(app);
app.mount('#app');

5.12 SSR 流式渲染示例

// server.js —— Vue 3.4+ SSR 流式渲染
import express from 'express';
import { createSSRApp, h } from 'vue';
import { renderToNodeStream } from 'vue/server-renderer';
import App from './App.vue';

const server = express();

server.get('*', async (req, res) => {
  const app = createSSRApp({
    render: () => h(App),
  });
  
  // 设置响应头
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('Transfer-Encoding', 'chunked');
  
  // 输出 HTML 头部
  res.write(`
    <!DOCTYPE html>
    <html>
    <head>
      <title>Vue SSR Streaming</title>
    </head>
    <body>
    <div id="app">
  `);
  
  // 流式渲染
  const stream = renderToNodeStream(app);
  stream.pipe(res, { end: false });
  
  stream.on('end', () => {
    res.write(`
      </div>
      <script type="module" src="/client.js"></script>
      </body>
      </html>
    `);
    res.end();
  });
  
  stream.on('error', (err) => {
    console.error('SSR Error:', err);
    res.status(500).send('Server Error');
  });
});

server.listen(3000, () => {
  console.log('Server running at http://localhost:3000');
});

6. 对比分析 | Comparative Analysis

6.1 与 React.lazy/Suspense 的对比

关键差异：

1. 配置完整性：Vue 内置 loading/error/timeout/重试，React 需配合 ErrorBoundary 与外部库。
2. 数据获取集成：Vue 的 async setup() 原生支持组件级数据获取与 Suspense 集成，React 需借助 React Query 等。
3. 并发渲染：React 18 的 Concurrent Rendering 支持中断与重试，Vue 基于响应式系统，无中断。

6.2 与 Solid.js lazy/Suspense 的对比

关键差异：

• Solid.js 的细粒度响应式使其性能更优，但学习成本较高。
• Vue 的组件级渲染粒度更易理解，社区生态更成熟。

6.3 与 Svelte 异步组件的对比

关键差异：

• Svelte 无原生 Suspense，需手动管理加载态。
• Svelte 的编译时优化使其运行时极小，但灵活性受限。

6.4 与 Angular 异步路由的对比

6.5 综合选型决策矩阵

7. 常见陷阱与最佳实践 | Pitfalls and Best Practices

7.1 陷阱：async setup() 在 Suspense 外使用

错误代码：

<!-- Component.vue -->
<script setup>
// async setup 必须在 Suspense 内使用
const data = await fetch('/api/data').then(r => r.json());
</script>

<!-- App.vue —— 未使用 Suspense -->
<template>
  <Component /> <!-- 警告：async setup() used without Suspense -->
</template>

正确做法：

<template>
  <Suspense>
    <template #default>
      <Component />
    </template>
    <template #fallback>
      <LoadingSpinner />
    </template>
  </Suspense>
</template>

7.2 陷阱：loading 闪烁

错误代码：

const AsyncComp = defineAsyncComponent({
  loader: () => import('./Comp.vue'),
  loadingComponent: LoadingSpinner,
  delay: 0, // 立即显示 loading，快速加载时闪烁
});

正确做法：

const AsyncComp = defineAsyncComponent({
  loader: () => import('./Comp.vue'),
  loadingComponent: LoadingSpinner,
  delay: 200, // 延迟 200ms，快速加载时不显示 loading
});

原理：delay 防止快速加载时 loading 闪烁，提升用户体验。200ms 是经验值，根据实际加载时间调整。

7.3 陷阱：未处理超时

错误代码：

const AsyncComp = defineAsyncComponent({
  loader: () => import('./Comp.vue'),
  loadingComponent: LoadingSpinner,
  errorComponent: ErrorDisplay,
  // 无 timeout，加载失败时永远显示 loading
});

正确做法：

const AsyncComp = defineAsyncComponent({
  loader: () => import('./Comp.vue'),
  loadingComponent: LoadingSpinner,
  errorComponent: ErrorDisplay,
  timeout: 10000, // 10 秒超时
});

7.4 陷阱：Suspense 未捕获错误

错误代码：

<Suspense>
  <template #default>
    <AsyncComponent />
  </template>
  <template #fallback>
    <LoadingSpinner />
  </template>
</Suspense>
<!-- 无 onErrorCaptured，错误向上传播导致整页崩溃 -->

正确做法：

<script setup>
import { ref, onErrorCaptured } from 'vue';

const error = ref(null);

onErrorCaptured((err) => {
  error.value = err;
  return false; // 阻止传播
});
</script>

<template>
  <div v-if="error">
    <ErrorDisplay :error="error" />
  </div>
  <Suspense v-else>
    <template #default>
      <AsyncComponent />
    </template>
    <template #fallback>
      <LoadingSpinner />
    </template>
  </Suspense>
</template>

7.5 陷阱：循环依赖导致加载失败

错误代码：

// A.js
import B from './B.js'; // B 又 import A，循环依赖

// A.vue
export default {
  components: { B },
};

说明：循环依赖在异步加载时更易暴露，Webpack/Vite 可能返回 undefined。

解决：

• 重构代码，消除循环依赖。
• 使用动态 import 延迟加载：const B = () => import('./B.vue')。

7.6 陷阱：chunk 命名冲突

错误代码：

// 多个异步组件未命名，Webpack 自动生成 0.js, 1.js...
const A = () => import('./A.vue');
const B = () => import('./B.vue');

正确做法：

// 使用 webpackChunkName 注释命名
const A = () => import(/* webpackChunkName: "a" */ './A.vue');
const B = () => import(/* webpackChunkName: "b" */ './B.vue');

7.7 陷阱：Suspense 嵌套过深

错误代码：

<Suspense>
  <Suspense>
    <Suspense>
      <Suspense>
        <Component /> <!-- 4 层嵌套，调试困难 -->
      </Suspense>
    </Suspense>
  </Suspense>
</Suspense>

建议：限制 Suspense 嵌套层级，通常 2 层足够。深层嵌套应重构组件结构。

7.8 陷阱：async setup 中使用生命周期钩子

错误代码：

export default {
  async setup() {
    // onMounted 在 await 之后注册，已晚于挂载
    const data = await fetchData();
    onMounted(() => {
      console.log('mounted', data); // 警告：onMounted called after await
    });
  },
};

正确做法：

export default {
  async setup() {
    onMounted(() => {
      console.log('mounted'); // 在 await 之前注册
    });
    
    const data = await fetchData();
    return { data };
  },
};

原理：Vue 的生命周期钩子需在 setup 同步执行期间注册，await 之后的代码异步执行，钩子注册失败。

7.9 最佳实践：合理使用 delay

// 根据 loader 平均加载时间调整 delay
const AsyncComp = defineAsyncComponent({
  loader: () => import('./Comp.vue'),
  loadingComponent: LoadingSpinner,
  delay: 200, // 若平均加载时间 < 200ms，loading 不显示
  timeout: 10000,
});

7.10 最佳实践：错误恢复

const AsyncComp = defineAsyncComponent({
  loader: () => import('./Comp.vue'),
  errorComponent: {
    template: `
      <div class="error">
        <p>Failed to load component</p>
        <button @click="$emit('retry')">Retry</button>
      </div>
    `,
    emits: ['retry'],
  },
  onError(err, retry, fail, attempts) {
    if (attempts <= 3) {
      setTimeout(retry, 1000 * attempts);
    } else {
      fail();
    }
  },
});

7.11 最佳实践：预加载关键路由

// router/index.ts
import { createRouter } from 'vue-router';

const routes = [
  { path: '/', component: () => import('./Home.vue') },
  { path: '/dashboard', component: () => import('./Dashboard.vue') },
  // 关键路由预加载
  { path: '/profile', component: () => import(/* webpackPrefetch: true */ './Profile.vue') },
];

const router = createRouter({ routes });

// 路由前置守卫中预加载下一页
router.beforeEach((to) => {
  if (to.meta.preloadNext) {
    const nextRoutes = findAdjacentRoutes(to);
    nextRoutes.forEach(route => route.component());
  }
});

7.12 最佳实践：chunk 分析与优化

// vite.config.ts —— 分析 chunk 大小
import { defineConfig } from 'vite';
import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [
    vue(),
    visualizer({
      filename: 'dist/stats.html',
      gzipSize: true,
      brotliSize: true,
    }),
  ],
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'vue-vendor': ['vue', 'vue-router', 'pinia'],
          'ui-vendor': ['element-plus'],
          'chart-vendor': ['echarts', 'vue-echarts'],
        },
      },
    },
  },
});

7.13 最佳实践：SSR 错误降级

// SSR 中处理异步组件错误
async function render(url) {
  const app = createSSRApp(App);
  
  // 捕获 Suspense 错误，降级为客户端加载
  app.config.errorHandler = (err) => {
    console.error('SSR Error:', err);
  };
  
  try {
    const html = await renderToString(app, {
      onError(err) {
        console.warn('SSR async error, fallback to client:', err);
      },
    });
    return html;
  } catch (err) {
    // 降级为 CSR
    return renderCSR(url);
  }
}

8. 工程实践 | Engineering Practice

8.1 项目结构组织

src/
├── components/
│   ├── async/                # 异步组件目录
│   │   ├── HeavyChart.vue
│   │   ├── MarkdownEditor.vue
│   │   └── DataGrid.vue
│   ├── common/               # 通用组件
│   │   ├── LoadingSpinner.vue
│   │   ├── ErrorDisplay.vue
│   │   └── Skeleton.vue
│   └── ...
├── composables/
│   ├── useAsyncComponent.ts  # 异步组件 Composable
│   └── usePreload.ts         # 预加载 Composable
├── utils/
│   ├── asyncComponents.ts    # 异步组件注册器
│   └── chunkAnalyzer.ts      # chunk 分析工具
├── router/
│   └── index.ts              # 路由配置（含懒加载）
└── main.ts                   # 应用入口

8.2 Vite 配置优化

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [
    vue(),
    visualizer({ open: false, gzipSize: true }),
  ],
  build: {
    target: 'es2020',
    cssCodeSplit: true, // CSS 代码分割
    rollupOptions: {
      output: {
        // 手动 chunk 分割
        manualChunks(id) {
          if (id.includes('node_modules')) {
            if (id.includes('vue') || id.includes('pinia')) {
              return 'vue-vendor';
            }
            if (id.includes('element-plus')) {
              return 'ui-vendor';
            }
            if (id.includes('echarts')) {
              return 'chart-vendor';
            }
            return 'vendor';
          }
        },
        // chunk 文件名带 hash
        chunkFileNames: 'assets/[name]-[hash].js',
        entryFileNames: 'assets/[name]-[hash].js',
        assetFileNames: 'assets/[name]-[hash].[ext]',
      },
    },
    // chunk 大小警告阈值
    chunkSizeWarningLimit: 500,
  },
  experimental: {
    // Vite 5+ 的预加载优化
    renderBuiltUrl(filename, { hostType }) {
      if (hostType === 'js') {
        return { relative: filename };
      }
      return filename;
    },
  },
});

8.3 Vue Router 懒加载

// router/index.ts
import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router';

const routes: RouteRecordRaw[] = [
  {
    path: '/',
    name: 'home',
    // 首页直接加载，提升首屏速度
    component: () => import('@/views/Home.vue'),
  },
  {
    path: '/dashboard',
    name: 'dashboard',
    // 仪表盘懒加载
    component: () => import('@/views/Dashboard.vue'),
    meta: { requiresAuth: true },
  },
  {
    path: '/profile',
    name: 'profile',
    component: () => import('@/views/Profile.vue'),
    meta: { preload: true }, // 标记预加载
  },
  {
    path: '/:pathMatch(.*)*',
    name: 'not-found',
    component: () => import('@/views/NotFound.vue'),
  },
];

const router = createRouter({
  history: createWebHistory(),
  routes,
});

// 预加载标记的路由
router.beforeEach((to) => {
  if (to.meta.preload) {
    // 加载下一级路由
    router.getRoutes().forEach(route => {
      if (route.meta?.preload && route.name !== to.name) {
        route.component?.();
      }
    });
  }
});

export default router;

8.4 单元测试

// tests/components/AsyncComponent.spec.ts
import { describe, it, expect, vi } from 'vitest';
import { mount, flushPromises } from '@vue/test-utils';
import { defineAsyncComponent, h, Suspense } from 'vue';
import AsyncComponent from '@/components/AsyncComponent.vue';

describe('AsyncComponent', () => {
  it('renders loading state initially', async () => {
    const wrapper = mount({
      components: { AsyncComponent },
      template: `
        <Suspense>
          <template #default>
            <AsyncComponent />
          </template>
          <template #fallback>
            <div class="loading">Loading...</div>
          </template>
        </Suspense>
      `,
    });
    
    expect(wrapper.find('.loading').exists()).toBe(true);
  });
  
  it('renders component after loading', async () => {
    const wrapper = mount(Suspense, {
      slots: {
        default: h(AsyncComponent),
        fallback: h('div', { class: 'loading' }, 'Loading...'),
      },
    });
    
    await flushPromises();
    expect(wrapper.find('.loading').exists()).toBe(false);
    expect(wrapper.text()).toContain('Async Component');
  });
  
  it('retries on loading failure', async () => {
    let attempts = 0;
    const loader = vi.fn(() => {
      attempts++;
      if (attempts < 3) {
        return Promise.reject(new Error('Network error'));
      }
      return Promise.resolve({ default: { template: '<div>Loaded</div>' } });
    });
    
    const AsyncComp = defineAsyncComponent({
      loader,
      onError(err, retry, fail, attemptCount) {
        if (attemptCount <= 3) retry();
        else fail();
      },
    });
    
    const wrapper = mount(Suspense, {
      slots: {
        default: h(AsyncComp),
        fallback: h('div', 'Loading'),
      },
    });
    
    await flushPromises();
    expect(attempts).toBe(3);
    expect(wrapper.text()).toContain('Loaded');
  });
});

8.5 集成测试

// tests/integration/route.spec.ts
import { describe, it, expect } from 'vitest';
import { mount } from '@vue/test-utils';
import { createRouter, createMemoryHistory } from 'vue-router';
import App from '@/App.vue';

describe('Route lazy loading', () => {
  it('loads route component on navigation', async () => {
    const router = createRouter({
      history: createMemoryHistory(),
      routes: [
        { path: '/', component: { template: '<div>Home</div>' } },
        { path: '/about', component: () => import('@/views/About.vue') },
      ],
    });
    
    const wrapper = mount(App, {
      global: {
        plugins: [router],
      },
    });
    
    await router.push('/');
    await router.isReady();
    expect(wrapper.text()).toContain('Home');
    
    await router.push('/about');
    await new Promise(resolve => setTimeout(resolve, 100)); // 等待异步加载
    expect(wrapper.text()).toContain('About');
  });
});

8.6 性能监控

// composables/useChunkPerformance.ts
import { onMounted, ref } from 'vue';

interface ChunkLoadMetric {
  name: string;
  loadTime: number;
  size: number;
  timestamp: number;
}

const metrics = ref<ChunkLoadMetric[]>([]);

export function useChunkPerformance() {
  onMounted(() => {
    // 监听 chunk 加载
    const observer = new PerformanceObserver((list) => {
      for (const entry of list.getEntries()) {
        if (entry.name.includes('.js')) {
          metrics.value.push({
            name: entry.name,
            loadTime: entry.duration,
            size: entry.transferSize || 0,
            timestamp: Date.now(),
          });
        }
      }
    });
    
    observer.observe({ entryTypes: ['resource'] });
  });
  
  return {
    metrics,
    getSlowChunks: (threshold = 1000) => metrics.value.filter(m => m.loadTime > threshold),
    getTotalSize: () => metrics.value.reduce((sum, m) => sum + m.size, 0),
  };
}

8.7 SSR 流式渲染实践

// server/index.ts —— Nuxt 3 风格的 SSR
import express from 'express';
import { createSSRApp, h } from 'vue';
import { renderToNodeStream } from 'vue/server-renderer';
import { createRouter } from './router';
import App from './App.vue';

const server = express();

server.use(express.static('public'));

server.get('*', async (req, res) => {
  const app = createSSRApp({
    render: () => h(App),
  });
  
  const router = createRouter();
  app.use(router);
  await router.push(req.url);
  
  // 设置 HTML 头部
  res.writeHead(200, { 'Content-Type': 'text/html' });
  res.write('<!DOCTYPE html><html><head><title>SSR</title></head><body><div id="app">');
  
  // 流式渲染
  const stream = renderToNodeStream(app);
  
  stream.on('data', (chunk) => {
    res.write(chunk);
  });
  
  stream.on('end', () => {
    res.write('</div><script type="module" src="/client.js"></script></body></html>');
    res.end();
  });
  
  stream.on('error', (err) => {
    console.error('SSR stream error:', err);
    // 降级为客户端渲染
    res.write('</div><script>window.__SSR_FAILED__ = true;</script>');
    res.write('<script type="module" src="/client.js"></script></body></html>');
    res.end();
  });
});

server.listen(3000);

8.8 调试工具

// devtools/asyncInspector.ts
import type { App } from 'vue';

export function setupAsyncInspector(app: App) {
  if (!import.meta.env.DEV) return;
  
  // 监听 chunk 加载
  const originalImport = window.__vite__loadDynamicImport;
  window.__vite__loadDynamicImport = async function (...args) {
    const start = performance.now();
    const result = await originalImport.apply(this, args);
    const duration = performance.now() - start;
    
    console.debug(
      `[async] Loaded ${args[0]} in ${duration.toFixed(2)}ms`,
      { size: result.__chunkSize || 'unknown' }
    );
    
    return result;
  };
  
  // Vue Devtools 自定义面板
  if (window.__VUE_DEVTOOLS_GLOBAL_HOOK__) {
    window.__VUE_DEVTOOLS_GLOBAL_HOOK__.emit('custom-inspector', {
      id: 'async-components',
      label: 'Async Components',
      icon: '⚡',
      tree: () => getAsyncComponentTree(app._instance),
    });
  }
}

function getAsyncComponentTree(instance: any): any {
  // 遍历组件树，收集异步组件信息
  return {
    name: instance.type.name || 'Anonymous',
    isAsync: !!instance.type.__asyncLoader,
    children: (instance.subTree?.children || []).map(getAsyncComponentTree),
  };
}

9. 案例研究 | Case Studies

9.1 案例一：Nuxt 3 的路由懒加载

Nuxt 3 默认将所有页面组件懒加载，无需手动配置：

// nuxt.config.ts
export default defineNuxtConfig({
  // Nuxt 自动将 pages/*.vue 懒加载
  pages: true,
  
  experimental: {
    // 启用组件自动导入
    componentIslands: true,
  },
});

// pages/about.vue 自动懒加载
// 无需手动 import() 或 defineAsyncComponent

设计要点：

1. 零配置：Nuxt 自动处理页面懒加载，开发者无需关心。
2. 预取策略：Nuxt 默认预取所有可见链接对应的 chunk。
3. Suspense 集成：Nuxt 的 <NuxtPage> 内置 Suspense，管理加载态。

9.2 案例二：Element Plus 的按需加载

Element Plus 通过异步组件实现按需加载：

// plugins/element-plus.ts
import { defineAsyncComponent } from 'vue';

// 按需加载 Element Plus 组件
const components = {
  ElButton: () => import('element-plus/es/components/button'),
  ElInput: () => import('element-plus/es/components/input'),
  ElSelect: () => import('element-plus/es/components/select'),
  ElTable: () => import('element-plus/es/components/table'),
};

export default defineNuxtPlugin((nuxtApp) => {
  for (const [name, loader] of Object.entries(components)) {
    nuxtApp.vueApp.component(name, defineAsyncComponent(loader));
  }
});

设计要点：

1. ES Module 按需：从 element-plus/es/components/ 导入，避免打包整个库。
2. 异步注册：组件首次使用时加载，未使用的组件不打包。
3. Tree Shaking 配合：与 Vite/Webpack 的 Tree Shaking 协同，进一步减小体积。

9.3 案例三：VitePress 的异步加载

VitePress 大量使用异步组件加载 Markdown 渲染器：

// VitePress 源码（简化）
import { defineAsyncComponent } from 'vue';

const MarkdownRenderer = defineAsyncComponent({
  loader: () => import('./MarkdownRenderer.vue'),
  loadingComponent: { template: '<div>Loading content...</div>' },
  errorComponent: { template: '<div>Failed to load content</div>' },
  delay: 0, // 立即显示 loading
  timeout: 30000, // 30 秒超时
});

export default {
  components: { MarkdownRenderer },
};

9.4 案例四：Vue Router 的懒加载

Vue Router 4 推荐使用动态 import 实现懒加载：

// router/index.ts
const routes = [
  {
    path: '/dashboard',
    component: () => import('@/views/Dashboard.vue'),
    // 路由独享的预加载
    meta: { 
      webpackPrefetch: true,
      webpackPreload: true,
    },
  },
];

const router = createRouter({ routes });

// 全局预加载策略
router.beforeEach(async (to) => {
  // 预加载目标路由的 chunk
  if (typeof to.matched[0]?.components?.default === 'function') {
    to.matched[0].components.default();
  }
});