Nuxt 的 Lazy 组件前缀

Nuxt 为自动导入的组件提供了 Lazy 前缀，可将组件转为异步加载以拆分代码、减小首屏体积。

但滥用会引发额外 HTTP 往返和交互延迟，本文讲清它的原理与使用边界。

在前端性能优化里，「懒加载（Lazy Loading）」是绕不开的关键词，图片懒加载、iframe 懒加载，乃至组件本身的懒加载。

Nuxt 基于 Vue，把组件懒加载做成了几乎零成本的能力：只需在组件名前加一个 Lazy 前缀即可。

问题在于：默认情况下，一个页面用到的所有组件都会被打进当前页面的 JavaScript 文件（例如 index.js）。

哪怕某个组件（比如一个默认隐藏的弹窗）只有在用户点击后才显示，它的代码依然会在首屏被下载和解析，白白增加了初始包体积、拖慢首屏加载。

Lazy 前缀正是用来解决这一痛点的。

但它并非「越多越好」， 用错地方反而会让性能更差。

Nuxt 自动导入与 Lazy 前缀是什么

Nuxt 会自动导入 components/ 目录下的组件，无需手动 import。

在此基础上，每个组件都会额外生成一个带 Lazy 前缀的版本。

也就是说，即便你的组件里没有写任何和「lazy」相关的东西，你依然可以直接这样使用：

<template>
  <!-- 普通导入：随当前页面一起打包 -->
  <AppFooter />

  <!-- 懒加载版本：需要时才加载 -->
  <LazyAppFooter />
</template>

不仅是自定义的组件，Nuxt 及各类模块提供的组件也都自带 Lazy 版本，比如：NuxtImage、NuxtLink、ClientOnly 等。

这套机制的实现可以在 Nuxt 官方仓库的 packages/nuxt/src/components/plugins/transform.ts 中找到。

它本质上是一个 transform 插件，负责为自动导入注册组件。核心逻辑大致是：

• 组件先以 PascalCase 名称注册（例如 AppFooter），并带上对应 mode（如 client、server 组件）。

• 随后再注册一个带 Lazy 前缀的 PascalCase 版本（例如 LazyAppFooter），并引入 async 模式。

当 mode 为 async 时，转换后的代码会使用 Vue 的 defineAsyncComponent，并在其中引用组件的动态 import：

import { defineAsyncComponent } from 'vue'

// 概念示意：Lazy 版本的组件被包装为异步组件
export const LazyAppFooter = defineAsyncComponent(
  () => import('~/components/AppFooter.vue')
)

defineAsyncComponent 是 Vue 的原生能力，允许定义不同步加载、而是异步加载的组件（例如通过动态 import 或返回 Promise 的 fetch）。

它的关键红利是开箱即用的代码分割（code splitting），组件被拆成独立 chunk，不必在首屏一次性全部加载。

注意区分

这里的代码分割是按组件拆分，和 Vue Router / Nuxt 按路由（by route） 的代码分割是两回事。

路由级别的拆分 Nuxt 已自动完成，无需你再手动处理，Lazy 前缀只针对组件。

Lazy 到底解决了什么问题

用一个最小 Demo 说明。应用结构很简单：app.vue 加载了 header、sidebar、footer；index 页面里有一个由 isOpen 这个 ref 控制的弹窗（modal），点击按钮时 isOpen 置为 true 打开，关闭时置回 false：

<script setup>
const isOpen = ref(false)
</script>

<template>
  <button @click="isOpen = true">打开弹窗</button>
  <AppModal v-if="isOpen" @close="isOpen = false" />
</template>

在生产构建下加载页面，会看到浏览器只请求了当前页面的 index.js 和入口文件。点击按钮弹出 modal 时，并没有加载任何新的组件文件。那么 modal 的内容从哪来？

答案是：它被打进了 index.js 里。如果把 index 这个 chunk 在新标签页打开并搜索关键词（比如弹窗文案 subscribe），会发现 modal 的模板、它 emit 的事件等都赫然在内。

原因很清楚：modal 只在 index 页面用到，且没有懒加载，于是被直接内联进了页面 JS。哪怕它只有在 v-if 触发时才显示，代码也会在首屏被加载，首屏体积因此比实际需要的更大，用户加载也更慢。

使用 Lazy 组件前缀

修复方式非常简单：进入 index 页面，给 AppModal 加上 Lazy 前缀即可。

<template>
  <button @click="isOpen = true">打开弹窗</button>
  <!-- 只需前缀改成 Lazy -->
  <LazyAppModal v-if="isOpen" @close="isOpen = false" />
</template>

这样组件就只会在真正需要时（即 v-if 为真时）才被加载。重新构建后再看浏览器：

阶段	未加 Lazy	加了 Lazy
首屏加载	index / 入口 JS（含 modal 代码）	index / 入口 JS（不含 modal）
点击按钮	无新请求，直接显示	加载独立的 modal chunk 后显示

modal 不再是 index.js 的一部分，而成为一个完全独立的组件 chunk。

唯一的代价是：点击后 JavaScript 需要现场下载，用户看到组件可能有轻微延迟。规避方式是在浏览器空闲（idle）时预取（prefetch） 该组件，这正是 Nuxt 默认对页面文件所做的事：当前页面资源加载完毕、且链接进入视口（viewport）时，NuxtLink 指向的页面会被自动预取。

为什么不能「全都懒加载」

既然这么好用，能不能把所有组件都加上 Lazy？比如在 app.vue 里：

<template>
  <!-- 反面示范：请勿这样做 -->
  <LazyAppHeader />
  <LazyAppBar />
  <LazyAppFooter />
</template>

重新构建后加载页面，会发现问题：首屏不再只有 index 和入口文件，还额外请求了 header、footer、sidebar 各自的文件。

• 对于服务端渲染（SSR） 的首次请求，多几个文件问题还不算大；
• 但一旦涉及交互性（interactivity），这就是大麻烦，尤其在页面间导航时体验明显变差；
• 在大型应用中更可怕：父组件懒加载所有子组件，子组件加载后又懒加载孙组件，层层递进（瀑布式加载），会造成严重的性能问题。

7 条可执行判断

1. 首屏 / 折叠线以上（above the fold）的内容不要懒加载，用户应立即看到的 header、sidebar、主要内容等。
2. v-if 后面、默认不显示的组件是懒加载的候选，典型如 modal、抽屉、下拉重内容等。
3. footer 一般可以安全懒加载，因为它通常在折叠线以下。
4. sidebar 若仅在移动端出现，可以酌情考虑懒加载。
5. 给懒加载组件加上 Lazy 前缀即可，Nuxt 已内置异步组件能力，无需额外写 defineAsyncComponent。
6. 必要时配合预取，在浏览器空闲、或链接进入视口时提前加载，抵消点击后的延迟。
7. 路由级拆分交给 Nuxt，Lazy 只用于组件级拆分，别把两者混为一谈。

注意事项

坑 / 场景	说明与建议
懒加载折叠线以上内容	会造成额外 HTTP 往返，且这类内容无法被 Nuxt 自动预取，反而拖慢体验。
全站无脑加 Lazy	触发瀑布式（父→子→孙）逐层懒加载，大型应用性能急剧恶化。
点击后可见延迟	懒加载组件的 JS 需现场下载解析，可能有短暂延迟；用预取缓解。
交互性权衡	若组件放进初始包：首屏更大，但交互即时可用；若懒加载：首屏更小，但需接受约 200ms 级的加载等待。按业务取舍。
与路由拆分混淆	Nuxt 已按路由自动拆分页面 JS，Lazy 仅针对组件，别重复造轮子。

核心结论（TL;DR）：Lazy 前缀是在 Nuxt 中「即写即用」创建异步组件的利器，非常适合懒加载那些非首屏、按需出现的组件；但切勿滥用，尤其是折叠线以上或属于应用外壳（如 header、sidebar）的内容，这类内容应让用户第一时间看到，不要懒加载。是否懒加载，本质是首屏体积与交互即时性之间的权衡。

相关链接

• Nuxt 官方仓库（含 Lazy Transform 插件）
• Vue 异步组件文档
• 原视频：The Lazy component prefix and when to use it - Nuxt Performance in Depth