---
title: "自动导入"
description: "Nuxt 会自动导入组件、composables、辅助函数和 Vue API。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/auto-imports"
---
# 自动导入

> Nuxt 会自动导入组件、composables、辅助函数和 Vue API。

Nuxt 会自动导入组件、composables 和 [Vue.js APIs](https://vue.zhcndoc.com/api/)，在整个应用中使用时无需显式导入。

```vue [app/app.vue]twoslash
<script setup lang="ts">
const count = ref(1) // ref 会自动导入
</script>
```

得益于其约定优于配置的目录结构，Nuxt 可以自动导入 [`app/components/`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/components)、[`app/composables/`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/composables) 和 [`app/utils/`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/utils) 中的内容。

与传统的全局声明不同，Nuxt 会保留类型信息、IDE 自动补全和提示，并且**仅包含在生产代码中实际使用的内容**。

<note>

在文档中，所有未显式导入的函数都会由 Nuxt 自动导入，可直接在代码中使用。你可以在 [API 部分](https://nuxt.zhcndoc.com/docs/4.x/api)中查找自动导入的组件、composables 和实用工具的参考。

</note>

<note>

在 [`server`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/server) 目录中，Nuxt 会自动导入 `server/utils/` 中导出的函数和变量。

</note>

<note>

你也可以通过配置 `nuxt.config` 文件中的 [`imports`](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#imports) 部分，自动导入自定义文件夹或第三方包中导出的函数。

</note>

## 内置自动导入

Nuxt 会自动导入函数和 composables，以执行[数据获取](https://nuxt.zhcndoc.com/docs/4.x/getting-started/data-fetching)、访问[应用上下文](https://nuxt.zhcndoc.com/docs/4.x/api/composables/use-nuxt-app)和[运行时配置](https://nuxt.zhcndoc.com/docs/4.x/guide/going-further/runtime-config)、管理[状态](https://nuxt.zhcndoc.com/docs/4.x/getting-started/state-management)，或定义组件和插件。

```vuetwoslash
<script setup lang="ts">
/* useFetch() 会自动导入 */
const { data, refresh, status } = await useFetch('/api/hello')
</script>
```

Vue 提供像 `ref` 或 `computed` 这样的响应式 API，以及生命周期钩子和辅助函数，这些都会被 Nuxt 自动导入。

```vuetwoslash
<script setup lang="ts">
/* ref() 和 computed() 会自动导入 */
const count = ref(1)
const double = computed(() => count.value * 2)
</script>
```

### Vue 与 Nuxt 的 Composables

当你使用由 Vue 和 Nuxt 提供的内置 Composition API composables 时，请注意其中许多依赖在正确的上下文（*context*）中被调用。

在组件生命周期期间，Vue 会通过一个全局变量追踪当前组件的临时实例（类似地，Nuxt 会追踪 `nuxtApp` 的临时实例），并在同一 tick 内取消设置它。这在服务器渲染时至关重要，既能避免跨请求状态污染（在两个用户之间泄露共享引用），也能避免在不同组件之间的泄漏。

这意味着（极少数情况除外）你不能在 Nuxt 插件、Nuxt 路由中间件或 Vue 的 setup 函数之外使用它们。除此之外，你必须同步使用它们——也就是说，不能在调用 composable 之前使用 `await`，除非是在 `<script setup>` 块中、使用 `defineNuxtComponent` 声明组件的 setup 函数中、在 `defineNuxtPlugin` 中或在 `defineNuxtRouteMiddleware` 中，这些场景会进行一次转换以在 `await` 之后仍保持同步上下文。

如果你收到类似 `Nuxt instance is unavailable` 的错误消息，那么很可能表示你在 Vue 或 Nuxt 生命周期的错误位置调用了 Nuxt composable。

<video-accordion title="观看 Alexander Lichter 的视频，了解如何避免“Nuxt instance is unavailable”错误" video-id="ofuKRZLtOdY">



</video-accordion>

<tip>

当在非 SFC 组件内使用需要 Nuxt 上下文的 composable 时，你需要用 `defineNuxtComponent` 包裹组件，而不是 `defineComponent`。

</tip>

<read-more to="https://nuxt.zhcndoc.com/docs/4.x/guide/going-further/experimental-features#asynccontext" icon="i-lucide-star">

了解 `asyncContext` 实验性功能，以便在异步函数中使用 Nuxt composables。

</read-more>

<read-more to="https://github.com/nuxt/nuxt/issues/14269#issuecomment-1397352832" target="_blank">

在该 GitHub 评论中查看完整说明。

</read-more>

**错误代码示例：**

```ts [composables/example.ts]twoslash
// 尝试在 composable 之外访问运行时配置
const config = useRuntimeConfig()

export const useMyComposable = () => {
  // 在这里访问运行时配置
}
```

**可行代码示例：**

```ts [composables/example.ts]twoslash
export const useMyComposable = () => {
  // 因为你的 composable 在生命周期中的正确位置被调用，
  // useRuntimeConfig 在这里可以正常工作
  const config = useRuntimeConfig()

  // ...
}
```

## 基于目录的自动导入

Nuxt 会直接自动导入在指定目录中创建的文件：

- `app/components/` 用于 [Vue 组件](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/components)。
- `app/composables/` 用于 [Vue composables](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/composables)。
- `app/utils/` 用于辅助函数和其他实用工具。

<link-example to="https://nuxt.zhcndoc.com/docs/4.x/examples/features/auto-imports">



</link-example>

<warning>

**自动导入的 ref 和 computed 不会在组件的 <template> 中被解包（unwrap）。** <br />


这是由于 Vue 对不是模板顶层的 refs 的处理方式所致。你可以在 [Vue 文档](https://vue.zhcndoc.com/guide/essentials/reactivity-fundamentals#caveat-when-unwrapping-in-templates) 中阅读更多信息。

</warning>

### 显式导入

Nuxt 为每个自动导入暴露了 `#imports` 别名，如果需要可以使用它来显式导入：

```vue
<script setup lang="ts">
import { computed, ref } from '#imports'

const count = ref(1)
const double = computed(() => count.value * 2)
</script>
```

### 禁用自动导入

如果你想禁用对 composables 和工具函数的自动导入，可以在 `nuxt.config` 文件中将 `imports.autoImport` 设置为 `false`。

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  imports: {
    autoImport: false,
  },
})
```

这将完全禁用自动导入，但仍可以从 `#imports` 中[显式导入](https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/auto-imports#explicit-imports)。

### 部分禁用自动导入

如果你希望像 `ref` 这样的框架特定函数仍保持自动导入，但希望禁用对你自己的代码（例如自定义 composables）的自动导入，可以在 `nuxt.config.ts` 文件中将 `imports.scan` 选项设置为 `false`：

```ts
export default defineNuxtConfig({
  imports: {
    scan: false,
  },
})
```

使用此配置：

- 像 `ref`、`computed` 或 `watch` 这样的框架函数仍然可以在不手动导入的情况下使用。
- 自定义代码（例如 composables）则需要在文件中手动导入。

<warning>

**注意：** 此设置有某些限制：

- 如果你的项目使用层（layers）结构，你需要显式从每个层导入 composables，而不能依赖自动导入。
- 这会破坏层系统的覆盖（override）功能。如果你使用 `imports.scan: false`，请确保理解此副作用并相应地调整你的架构。

</warning>

## 自动导入组件

Nuxt 也会自动从你的 `~/components` 目录导入组件，尽管这是与自动导入 composables 和工具函数分别配置的。

<read-more to="https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/components">



</read-more>

要禁用从你自己的 `~/components` 目录自动导入组件，你可以将 `components.dirs` 设置为空数组（但请注意，这不会影响由模块添加的组件）。

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  components: {
    dirs: [],
  },
})
```

## 从第三方包自动导入

Nuxt 也允许从第三方包中进行自动导入。

<tip>

如果你正在使用该包的 Nuxt 模块，该模块很可能已经为该包配置了自动导入。

</tip>

例如，你可以像下面这样启用从 `vue-i18n` 包自动导入 `useI18n` composable：

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  imports: {
    presets: [
      {
        from: 'vue-i18n',
        imports: ['useI18n'],
      },
    ],
  },
})
```

<video-accordion title="观看 Alexander Lichter 的视频，了解如何轻松设置自定义自动导入" video-id="FT2LQJ2NvVI">



</video-accordion>


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.