Vue中defineAsyncComponent用于异步加载非首屏必需组件,减小主包体积、提升FCP;支持loading/error处理及手动触发加载,与路由懒加载配合实现页面级和组件级双重优化。

Vue 单文件组件(SFC)中使用 defineAsyncComponent,核心是把重型、非首屏必需的子组件从同步引入改为异步加载,从而减小主包体积、加快首屏渲染(FCP)。它不改变组件逻辑,只改变加载时机。
直接在 script setup 中定义异步组件
这是最常用、最简洁的方式。适用于弹窗、编辑器、图表等“点开才用”的场景:
- 用
defineAsyncComponent包裹动态import(),返回一个可注册的组件引用 - 在
components选项或app.component()全局注册时使用该引用 - 模板中像普通组件一样使用,Vue 会在首次渲染时自动触发加载
示例:
<script setup lang="ts">
import { defineAsyncComponent } from 'vue'
// 异步加载富文本编辑器(不进主包)
const RichEditor = defineAsyncComponent(() =>
import('@/components/RichEditor.vue')
)
// 异步加载大型图表组件
const DataChart = defineAsyncComponent(() =>
import('@/components/DataChart.vue')
)
</script>
<template>
<button @click="showEditor = true">打开编辑器</button>
<RichEditor v-if="showEditor" />
<DataChart :data="chartData" />
</template>
带 loading 和 error 的健壮写法
网络不稳定或资源加载失败时,用户需要明确反馈。通过配置对象可内置加载态与错误态:
立即学习“前端免费学习笔记(深入)”;
-
loadingComponent:建议复用项目中的通用LoadingSpinner或简单文字占位 -
delay设为200:避免快速加载时 loading 一闪而过 -
timeout建议设为5000–10000:覆盖弱网场景,超时后显示 errorComponent -
errorComponent应提供重试机制(如按钮触发load())
示例:
const AsyncModal = defineAsyncComponent({
loader: () => import('@/components/BigModal.vue'),
loadingComponent: { template: '<div class="loading-sm">加载中…</div>' },
errorComponent: {
template: '<button @click="$emit(\'retry\')">加载失败,点击重试</button>',
emits: ['retry']
},
delay: 200,
timeout: 8000
})
配合条件控制,真正按需触发
有些组件不仅“用到才加载”,还希望“用户明确操作后才开始加载”。这时可结合 ref + v-if + 显式 import():
- 先声明
const Comp = ref(),模板中用<component :is="Comp"></component> - 点击按钮时执行
async函数,await import()后赋值给Comp.value - 这样加载时机完全由业务逻辑控制,适合有前置校验或权限判断的场景
示例:
<script setup lang="ts">
import { ref } from 'vue'
const Editor = ref()
const loadEditor = async () => {
const mod = await import('@/components/Editor.vue')
Editor.value = mod.default
}
</script>
<template>
<button @click="loadEditor">初始化编辑器</button>
<component :is="Editor" v-if="Editor" />
</template>
和路由懒加载的区别与配合
单文件组件内用 defineAsyncComponent 是“组件级”拆分;而路由配置里的 component: () => import(...) 是“页面级”拆分:
- 路由级拆包优先做——它影响最大,几乎必配
- 组件级拆包用于路由内部的重型子模块,比如详情页里的 PDF 预览器、Excel 导入弹窗
- 两者可叠加:一个异步路由页面里,再用
defineAsyncComponent加载其内部异步子组件
例如:/report 页面本身已路由懒加载,但其中的 <exportdialog></exportdialog> 可进一步用 defineAsyncComponent 拆出,避免用户点导出前就下载 Excel 库代码。


















