自动导入 · 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 公开了响应式 API，如 ref 或 computed，以及生命周期钩子和 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 提供的内置组合式 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 处理非模板顶层的 ref 的方式。你可以在 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 友好的使用。