v3.16
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 提供的内置组合 API 组合函数时，要注意它们中的许多依赖于在正确的 上下文 中调用。

在组件生命周期中，Vue 通过全局变量跟踪当前组件的临时实例（同样，Nuxt 跟踪 nuxtApp 的临时实例），然后在同一 tick 中取消设置。这在服务器渲染时至关重要，既可以避免跨请求的状态污染（在两个用户之间泄漏共享引用），也可以避免不同组件之间的泄漏。

这意味着（极少数例外情况下）你不能在 Nuxt 插件、Nuxt 路由中间件或 Vue 设置函数之外使用它们。此外，必须同步使用它们——即，在调用组合函数之前，不能使用 await，除非在 <script setup> 块中，或者在使用 defineNuxtComponent 声明的组件的 setup 函数中，或在 defineNuxtPlugin 或 defineNuxtRouteMiddleware 中，在这里我们执行转换以保持同步上下文，即使在 await 之后。

如果你收到类似 Nuxt instance is unavailable 的错误消息，这可能意味着你在 Vue 或 Nuxt 生命周期的错误位置调用了 Nuxt 组合函数。

观看 Alexander Lichter 的视频，了解如何处理组合函数中的异步代码并修复你的应用中的 Nuxt instance is unavailable 问题。
当在非 SFC 组件中使用需要 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 直接自动导入在定义的目录中创建的文件：

Read and edit a live example in Docs > Examples > Features > Auto Imports.
自动导入的 ref 和 computed 在组件的 <template> 中不会被解构。
这是由于 Vue 在处理不在模板的顶层的 refs 时的工作方式。你可以在 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']
      }
    ]
  }
})
观看 Alexander Lichter 的视频，了解如何轻松设置自定义自动导入。