组件自动导入

15-1

在原生 Vue 里，你想在 A 组件里用 B 组件，得先在 A 里 import B，再注册，才能用 <B> 标签。页面一多、组件一多，光是写 import 就够烦的，还容易漏。

Nuxt 把这个麻烦事替你接过去了。它约定了一个 app/components/ 目录：你只要把 .vue 文件放进去，Nuxt 启动时会自动扫描并全局注册，之后在任意组件的模板里都能直接用，不用 import。这就是组件自动导入（auto-imports）。

<template>
  <span>
    <slot />
  </span>
</template>

<template>
  <div>
    <h1>欢迎来到首页</h1>
    <AppAlert>
      这是一个自动导入的组件。
    </AppAlert>
  </div>
</template>

注意到没有？app.vue 里直接写了 <AppAlert>，没有任何 import 语句。

15-2

组件标签名由「文件路径 + 文件名」拼成，并且采用大驼峰（PascalCase）。规则很简单：

• components/AppAlert.vue → 模板里用 <AppAlert>
• components/BaseButton.vue → <BaseButton>
• components/common/Card.vue → 注意目录也会被拼进去，变成 <CommonCard>

也就是说，放进子目录的组件，目录名会作为前缀加到组件名前面。Nuxt 能自动「钻进」嵌套子目录，把整条相对路径都组合进名字里。

<template>
  <div class="card">
    <slot />
  </div>
</template>

<template>
  <CommonCard>
    卡片内容
  </CommonCard>
</template>

15-3

Vue 官方建议组件名用多单词，避免和未来的 HTML 标签撞名。Nuxt 的「路径+文件名」命名刚好帮了你：即便文件叫 Card.vue，加上目录前缀 CommonCard 也已经是多单词了，安全。

但也要当心：文件可以放在不同路径却取相同文件名，比如 components/Card.vue 和 components/common/Card.vue，它们会变成 <Card> 和 <CommonCard>，看起来不同，找起来却容易混。组件很多时，有人偏好把所有组件平铺放在 components/ 根目录、用完整名字区分。两种方式都行，选适合你团队的就好。

15-4

有些组件只能在浏览器里跑（比如用到了 window、本地存储），有些只在服务端渲染就行。Nuxt 用文件后缀帮你区分：

• SomeComp.client.vue：只在客户端加载，服务端不渲染它的内容。
• SomeComp.server.vue：只在服务端渲染，渲染逻辑不会被打进客户端打包里，能减小体积。

<template>
  <div ref="el">这里依赖浏览器的图表库</div>
</template>

<template>
  <span>服务端时间：{{ new Date().toISOString() }}</span>
</template>

15-5

自动导入虽好，但极少数团队出于规范原因想强制显式 import。可以在 nuxt.config 里关掉：

export default defineNuxtConfig({
  imports: {
    autoImport: false,
  },
})

关掉之后，Vue 的 ref、computed 这些就得用 #imports 显式引入了：

import { computed, ref } from '#imports'

const count = ref(1)
const double = computed(() => count.value * 2)

15-6

Nuxt 3 的组件目录在项目根 components/，Nuxt 4 改到 app/components/。功能与命名规则完全一致，老项目不强制迁移。

15-7

你可能会好奇：免 import 直接用 <AppAlert>、useRoute，编辑器为什么还能补全、不报错？答案是 Nuxt 在启动和类型检查时，自动生成了 .nuxt/components.d.ts、.nuxt/imports.d.ts 这类声明文件，把「哪些组件/函数可用」写进了类型系统。所以自动导入不等于「全局魔术变量」，它依然有完整类型支持。

15-8

默认情况下组件在 app/components/。但在更大的项目或用 Nuxt 层（Layers）做复用封装时，组件目录可以不止一个。这块属于进阶用法，初学阶段不必深究，只要记住：Nuxt 的默认行为已经覆盖了大多数场景，需要定制时框架也留好了口子。

15-9

Nuxt 给每个自动导入的组件，都额外生成了一个 Lazy 开头的异步版本。比如 app/components/Chart.vue，你不仅能用 <Chart>，还能用 <LazyChart>。两者的区别在于时机：

• <Chart> 会在首屏就把它对应的代码一起加载进来；
• <LazyChart> 等到这个组件真正要出现在视图里，才去请求那份代码。

对于很重、又不一定立刻显示的组件——比如图表库、弹窗、折叠面板里的内容——用 Lazy 版本能明显减小首屏加载量。它本质就是 Vue 的异步组件，Nuxt 帮你自动包好了，你只需在名字前加 Lazy。

15-10

自动导入虽好，但你随时可以反过来显式 import，两者不冲突。比如你只想在某个文件里用到 AppAlert，又想靠 ESLint 校验「确实用到了、没有多余导入」，就正常写：

<script setup lang="ts">
import AppAlert from '~/components/AppAlert.vue'
</script>

Nuxt 不会因为你自己写了 import 就报错。显式写法在「组件只在少数地方出现」时反而更清晰，也方便做依赖分析。注意 Nuxt 4 里 ~/ 指向的是 app/ 目录，所以 ~/components/AppAlert.vue 正确指向 app/components/AppAlert.vue。

15-11

Nuxt 自动导入的组件，在模板里用大驼峰 <AppAlert> 或短横线 <app-alert> 都能识别，Vue 会自动对应到同一个组件。一个常见习惯：在 .vue 模板里写 <AppAlert>，在 JSX / TSX 里写 <AppAlert />。两种写法没有「哪个才对」，团队统一就好。

15-12

前面说过 Nuxt 会「钻进」子目录，把目录名拼进组件名。这里有个实际坑：目录层级深了以后，组件名会变得很长，比如 app/components/form/input/Text.vue 会变成 <FormInputText>。名字长不是问题，问题是容易拼错。

解决办法有两个：要么在 nuxt.config 里给 components 配置 pathPrefix: false 让子目录不带前缀（此时只叫 <Text>，但要自己保证不重名）；要么接受前缀、靠 IDE 自动补全避免手敲。绝大多数团队选后者，因为前缀天然避免了同名冲突。

15-13

把 .vue 丢进 app/components/，组件名由「路径+文件名」自动生成，模板里直接用，不用 import。需要限定运行环境就用 .client.vue / .server.vue 后缀；想减小首屏就加 Lazy 前缀。下一章我们看比组件更大一层的复用单位：布局。