Vue 3 中定义异步组件需使用 defineAsyncComponent 包裹 import() 函数，首次挂载时才加载；支持 loading/error 组件、延迟显示、超时重试，并可配合 Suspense 简化状态管理。

Vue 3 中定义异步组件，核心就是用 defineAsyncComponent 包裹一个动态导入（import()）函数，让组件在真正需要渲染时才加载。

它不是语法糖，而是一个明确的、运行时可控制的机制——Vue 不会在初始化时解析它，只在 <component :is="..."></component> 或直接写在模板中被首次挂载时，才触发加载逻辑。

---

最简定义方式

import { defineAsyncComponent } from 'vue'

const AsyncModal = defineAsyncComponent(() => import('./Modal.vue'))

这个 AsyncModal 就是一个“代理组件”：

• 它本身体积极小；
• 模板里写 <asyncmodal></asyncmodal>，Vue 会等它首次进入 DOM 才执行 import('./Modal.vue')；
• 加载成功后，把真实组件实例替换上去，props、插槽、事件全部透传，对使用者完全透明。

---

带加载与错误处理的定义

适合需要用户体验控制的场景，比如弹窗、详情页、编辑器模块：

立即学习“前端免费学习笔记（深入）”；

Springboot Vue Builder

从零开始编排 SpringBoot+Vue 全栈项目工作流，适用于新建全栈项目或完整脚手架请求，触发后依次调用 product‑spec‑builder（需求调研）等模块。

下载

import { defineAsyncComponent } from 'vue'
import LoadingSpinner from './LoadingSpinner.vue'
import ErrorFallback from './ErrorFallback.vue'

const AsyncEditor = defineAsyncComponent({
  loader: () => import('./Editor.vue'),
  loadingComponent: LoadingSpinner,
  errorComponent: ErrorFallback,
  delay: 300,     // 300ms 内不显示 loading，防闪
  timeout: 5000,  // 超过 5 秒触发 errorComponent
  onError(error, retry, fail, attempts) {
    if (error.name === 'ChunkLoadError' && attempts < 2) {
      retry()
    } else {
      fail()
    }
  }
})

关键点说明：

• loader 是必填项，必须返回 Promise；
• loadingComponent 和 errorComponent 是普通 Vue 组件，不是字符串名；
• delay 和 timeout 单位是毫秒，注意 delay 只影响 loading 显示时机，不影响实际加载；
• onError 提供重试能力，retry() 会重新调用 loader，fail() 则直接展示 errorComponent。

---

配合 Suspense 使用更简洁

如果你不需要自定义 loading/error 组件，而是统一管理加载状态，推荐用 <suspense></suspense>：

<template>
  <Suspense>
    <template #default>
      <AsyncReport />
    </template>
    <template #fallback>
      <div class="skeleton">Loading report...</div>
    </template>
  </Suspense>
</template>

<script setup>
import { defineAsyncComponent } from 'vue'
const AsyncReport = defineAsyncComponent(() => import('./Report.vue'))
</script>

此时 AsyncReport 不用配 loadingComponent，<suspense></suspense> 全局接管 fallback 行为，语义更清晰，也更容易复用。

---

注册方式注意点

• 局部注册（推荐）：直接在 components 选项或 <script setup></script> 中声明，按需使用；
• 全局注册（慎用）：

  app.component('AsyncChart', defineAsyncComponent(() => import('./Chart.vue')))

  这样所有地方都能用 <asyncchart></asyncchart>，但失去了按需加载的语义控制，容易误用。

不复杂但容易忽略。