自动导入

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 暴露了像 refcomputed 这样的响应式 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 函数中,或在 defineNuxtPlugindefineNuxtRouteMiddleware 中,在这里我们执行转换以保持同步上下文,即使在 await 之后。

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

当在非 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.
自动导入的 refcomputed 在组件的 <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
  }
})

使用此配置:

  • refcomputedwatch 这样的框架函数将仍然可以在不需要手动导入的情况下工作。
  • 自定义代码,例如组合函数,需要在你的文件中手动导入。
注意: 此设置有某些限制:
  • 如果你按照层次结构组织项目,则需要显式导入每个层中的组合函数,而不能依赖于自动导入。
  • 这会破坏层系统的覆盖特性。如果使用 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']
      }
    ]
  }
})