v3
GitHub

自动导入

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

Nuxt 自动导入组件、组合函数和 Vue.js API，使您无需显式导入便可在整个应用中使用它们。

app.vue
<script setup lang="ts">
const count = ref(1) // ref 是自动导入的
</script>

多亏了其约定优于配置的目录结构，Nuxt 可以自动导入您的 components/、composables/ 和 utils/ 目录内的内容。

与传统的全局声明不同，Nuxt 保留了类型定义、IDE 补全和提示，并且只包含生产代码中实际使用的内容。

在文档中，每个未显式导入的函数均由 Nuxt 自动导入，且可以直接在您的代码中使用。您可在 API 部分 查找自动导入的组件、组合函数和工具的参考。
在 server 目录中，Nuxt 会自动导入来自 server/utils/ 的导出函数和变量。
您还可以通过配置 nuxt.config 文件的 imports 部分，自动导入自定义文件夹或第三方包中导出的函数。

内置自动导入

Nuxt 自动导入用于执行数据获取、访问应用上下文和运行时配置、管理状态以及定义组件和插件的函数和组合函数。

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

Vue 提供了诸如 ref、computed 的响应式 API，以及生命周期钩子和辅助函数，这些都由 Nuxt 自动导入。

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

Vue 和 Nuxt 组合函数

在使用 Vue 和 Nuxt 提供的内置 Composition API 组合函数时，请注意许多组合函数要求在正确的_上下文_中调用。

在组件生命周期内，Vue 会通过一个全局变量跟踪当前组件的临时实例（Nuxt 类似地跟踪 nuxtApp 的临时实例），随后在同一个事件循环周期内取消这个跟踪。此机制在服务端渲染时尤为重要，用于避免跨请求状态污染（防止两个用户间共享引用泄漏）以及防止组件间状态泄漏。

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

如果您遇到类似 Nuxt instance is unavailable 的错误提示，通常意味着您在 Vue 或 Nuxt 生命周期中的错误位置调用了 Nuxt 组合函数。

当在非单文件组件中使用需要 Nuxt 上下文的组合函数时，您需要使用 defineNuxtComponent 来包装组件，而非使用 defineComponent
查看 asyncContext 实验性功能，用于在异步函数中使用 Nuxt 组合函数。
查看该 GitHub 评论中的完整解释。

错误代码示例：

composables/example.ts
// 试图在组合函数外部访问运行时配置
const config = useRuntimeConfig()

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

正确代码示例：

composables/example.ts
export const useMyComposable = () => {
  // 因为组合函数在生命周期中的正确位置调用，
  // 所以 useRuntimeConfig 这里可用
  const config = useRuntimeConfig()

  // ...
}

基于目录的自动导入

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

  • components/ 目录中的 Vue 组件。
  • composables/ 目录中的 Vue 组合函数。
  • utils/ 目录中的辅助函数和其他实用工具。
Read and edit a live example in Docs > Examples > Features > Auto Imports.
自动导入的 ref 和 computed 在组件 <template> 中不会被解包。
这是由于 Vue 对非顶层引用的响应式处理机制导致。您可以在 Vue 文档 中了解更多。

显式导入

Nuxt 提供 #imports 别名，您可以通过它显式导入自动导入的内容，以满足需要时的引用：

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

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

禁用自动导入

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

nuxt.config.ts
export default defineNuxtConfig({
  imports: {
    autoImport: false
  }
})

此配置将完全禁用自动导入，但仍可通过 #imports 使用显式导入。

部分禁用自动导入

如果您希望框架特定的函数如 ref 仍然自动导入，但希望禁用自身代码（例如自定义组合函数）的自动导入，可以在 nuxt.config.ts 中将 imports.scan 选项设置为 false：

export default defineNuxtConfig({
  imports: {
    scan: false
  }
})

此配置下：

  • 框架函数如 ref、computed、watch 等仍可免手动导入使用。
  • 自定义代码（如组合函数）则需在文件中手动导入。
注意： 此设置存在一定限制：
  • 若项目采用分层结构，需对各层的组合函数进行显式导入，不能依赖自动导入。
  • 这会破坏分层系统的覆盖功能。使用 imports.scan: false 前，请充分理解此副作用，并相应调整架构设计。

自动导入组件

Nuxt 也会自动导入您的 ~/components 目录下的组件，尽管这项配置独立于组合函数和工具函数的自动导入。

Read more in Docs > Guide > Directory Structure > Components.

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

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

来自第三方包的自动导入

Nuxt 还支持从第三方包自动导入。

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

例如，您可以这样启用从 vue-i18n 包自动导入 useI18n 组合函数：

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