自动导入 · Nuxt 概念

Nuxt 自动导入组件、组合式函数和 Vue.js API，以便在您的应用程序中使用，而无需显式导入它们。

app.vue

<script setup lang="ts">
const count
 = ref
(1) // ref is auto-imported
</script>

由于其约定式的目录结构，Nuxt 可以自动导入您的 components/、composables/ 和 utils/。

与经典全局声明相反，Nuxt 保留类型、IDE 补全和提示，并且仅包含在您的生产代码中使用的内容。

在文档中，每个未显式导入的函数都由 Nuxt 自动导入，并且可以在您的代码中直接使用。您可以在 API 部分找到自动导入的组件、组合式函数和实用程序的参考。

在 server 目录中，Nuxt 自动导入从 server/utils/ 导出的函数和变量。

您还可以通过配置 nuxt.config 文件的 imports 部分，自动导入从自定义文件夹或第三方包导出的函数。

内置自动导入

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

<script setup lang="ts">
/* useFetch() is auto-imported */
const { data
, refresh
, status
 } = await useFetch
('/api/hello')
</script>

Vue 3 公开了诸如 ref 或 computed 之类的响应式 API，以及 Nuxt 自动导入的生命周期钩子和辅助函数。

<script setup lang="ts">
/* ref() and computed() are auto-imported */
const count
 = ref
(1)
const double
 = computed
(() => count
.value
 * 2)
</script>

Vue 和 Nuxt 组合式函数

当您使用 Vue 和 Nuxt 提供的内置 Composition API 组合式函数时，请注意，它们中的许多函数都依赖于在正确的上下文中调用。

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

这意味着（极少数例外）您不能在 Nuxt 插件、Nuxt 路由中间件或 Vue setup 函数之外使用它们。最重要的是，您必须同步使用它们 - 也就是说，您不能在调用组合式函数之前使用 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

// trying to access runtime config outside a composable
const config
 = useRuntimeConfig
()

export const useMyComposable
 = () => {
  // accessing runtime config here
}

工作代码的示例

composables/example.ts

export const useMyComposable
 = () => {
  // Because your composable is called in the right place in the lifecycle,
  // useRuntimeConfig will work here
  const config
 = useRuntimeConfig
()

  // ...
}

基于目录的自动导入

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

components/ 用于 Vue 组件。
composables/ 用于 Vue 组合式函数。
utils/ 用于辅助函数和其他实用程序。

在文档 > 示例 > 功能 > 自动导入中阅读和编辑实时示例。

自动导入的 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 目录导入组件，尽管这是与自动导入组合式函数和实用程序函数分开配置的。

在文档 > 指南 > 目录结构 > 组件中阅读更多内容。

要禁用从您自己的 ~/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 的视频，了解如何轻松设置自定义自动导入。

升级指南

了解如何升级到最新的 Nuxt 版本。

Vue.js 开发

Nuxt 使用 Vue.js 并添加了诸如组件自动导入、基于文件的路由和组合式函数等功能，以便于 SSR 友好的使用。