defineAsyncComponent 异步组件加载

当应用体积逐渐增大时，把所有组件打包进一个 JS 文件会导致首屏加载变慢。异步组件允许你只在需要某个组件时才去加载对应的代码块，从而减少初始包的体积。Vue 3 提供了 defineAsyncComponent 方法来声明异步组件，它比 Vue 2 的动态 import() 更加灵活且容错性更强。

基本用法

你可以用 defineAsyncComponent 包装一个返回 Promise 的加载函数，通常配合 ES 模块的动态 import() 使用：

import { defineAsyncComponent } from 'vue'

const AsyncUserCard = defineAsyncComponent(() =>
  import('./components/UserCard.vue')
)

在模板中，它和普通组件一样使用：

<template>
  <AsyncUserCard v-if="showCard" />
</template>

当 AsyncUserCard 出现在视图中时，Vue 才会发起网络请求加载对应的 UserCard.vue 文件，加载完成后自动渲染。

处理加载状态

网络慢或组件文件较大时，加载会有延迟。defineAsyncComponent 支持传入一个完整的配置对象，来处理加载中和加载失败的状态，避免页面出现空白或卡死。

const AsyncUserCard = defineAsyncComponent({
  // 加载函数
  loader: () => import('./components/UserCard.vue'),

  // 加载时使用的占位组件
  loadingComponent: LoadingSpinner,

  // 展示加载组件前的延迟时间（ms），避免闪烁
  delay: 200,

  // 加载失败时使用的错误组件
  errorComponent: ErrorDisplay,

  // 超时时间（ms），超时视为失败
  timeout: 3000,

  // 重试时的回调，可以在此尝试重新加载
  onError(error, retry, fail, attempts) {
    if (attempts <= 2) {
      retry() // 最多重试2次
    } else {
      fail()
    }
  }
})

这样用户体验会非常平滑：

快速网络下（< 200ms），组件直接渲染，看不到 loading。
加载较慢时，200ms 后显示加载动画。
若网络异常或超时，显示错误提示，甚至可以点击按钮触发 retry。

与动态组件的配合

异步组件和 <component :is> 结合使用也很自然。例如一个根据用户角色动态加载不同后台面板的场景：

<template>
  <component :is="currentPanel" />
</template>

<script setup>
import { computed } from 'vue'
import { defineAsyncComponent } from 'vue'

const panels = {
  admin: defineAsyncComponent(() => import('./AdminPanel.vue')),
  editor: defineAsyncComponent(() => import('./EditorPanel.vue')),
  viewer: defineAsyncComponent(() => import('./ViewerPanel.vue'))
}

const currentPanel = computed(() => panels[userRole.value])
</script>

每个面板组件都会被单独拆分成一个 chunk，只有访问对应角色功能时才会加载，进一步减少了不必要的网络开销。

与 Suspense 的结合（实验性）

Vue 3 还提供了实验性的 <Suspense> 组件，它能够更优雅地处理异步依赖的加载状态。当异步组件作为 <Suspense> 的 default 插槽内容时，可以在外层统一定义 loading 和错误状态，而不必在每个组件配置中重复定义。

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

这种方式适合多个异步组件同时加载的场景，能够整体控制加载中渲染的 UI。

注意事项

懒加载不是“无处不加”：只在体积较大且不常用的组件上使用异步加载（如弹窗、图表、富文本编辑器等），不要为了拆分而拆分，过多的 chunk 可能导致请求瀑布。
组件v-model绑定正常：异步组件加载后完全等同于普通组件，所有 Props、事件双向绑定均可照常工作。
defineAsyncComponent 返回的是组件定义，可以直接注册全局或局部使用，本质是包装过的异步组件工厂。

通过 defineAsyncComponent，你可以用很小的改动实现组件的按需加载，显著提升首屏性能，同时提供了完善的加载与错误处理能力，非常适合中大型应用的性能优化。