Auto-imports

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

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

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

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

内置自动导入

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

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

Vue 公开了像 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 内置的组合式 API（Composition API）函数时，请注意许多函数依赖于在正确的 上下文 中调用。

在组件生命周期中，Vue 会通过全局变量追踪当前组件的临时实例（类似地，Nuxt 也会追踪 nuxtApp 的临时实例），并在同一时间点（tick）取消设置。这在服务器渲染（SSR）中至关重要：

• 避免跨请求状态污染（防止两个用户之间共享引用导致数据泄露）；
• 避免不同组件间的状态泄漏。

这意味着（除极少数例外）：

1. 禁止在 Nuxt 插件、Nuxt 路由中间件或 Vue setup 函数之外调用这些函数。
2. 必须同步使用它们——即调用组合式函数前不能使用 await，除非位于以下场景中：

• <script setup> 代码块内；
• 通过 defineNuxtComponent 声明的组件 setup 函数中；
• defineNuxtPlugin 或 defineNuxtRouteMiddleware 内（这些场景下会执行转换以保持同步上下文，即使存在 await）。

若出现错误提示 Nuxt instance is unavailable，很可能是因为你在 Vue 或 Nuxt 生命周期的错误位置调用了 Nuxt 组合式函数。

错误代码示例：

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

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

正确代码示例：

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/ 用于辅助函数和其他实用程序。

显式导入

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。

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

这将完全禁用自动导入，但仍然可以从 #imports 使用 显式导入。

部分禁用自动导入

如果您希望像 ref 这样的框架特定函数保持自动导入，但希望禁用您自己代码（例如，自定义组合式函数）的自动导入，您可以在 nuxt.config.ts 文件中将 imports.scan 选项设置为 false：

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

通过此配置：

• 像 ref、computed 或 watch 这样的框架函数仍然可以在不需要手动导入的情况下工作。
• 自定义代码（例如组合式函数）将需要在您的文件中手动导入。

自动导入组件

Nuxt 还会自动导入 ~/components 目录中的组件，尽管这与自动导入组合式函数和实用工具函数是分开配置的。

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

export default defineNuxtConfig({
  components: {
    dirs: []
  }
})

从第三方包自动导入

Nuxt 还允许从第三方包自动导入。

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

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