自动导入机制原理与调试

// Vue API — 无需 import
ref, reactive, computed, watch, watchEffect
onMounted, onUnmounted, onBeforeMount
nextTick, defineProps, defineEmits, defineExpose
 
// Nuxt Composables — 无需 import
useFetch, useAsyncData, useLazyFetch
useRoute, useRouter, navigateTo
useState, useCookie, useRuntimeConfig
useHead, useSeoMeta, useNuxtApp

// app/composables/index.ts — 用 index 文件聚合深层导出
export { useDebounce } from './utils/useDebounce'
export { useThrottle } from './utils/useThrottle'

// 你写的代码（无 import）：
const count = ref(0)
const { data } = await useFetch('/api/videos')
 
// Nuxt 编译后的实际代码：
import { ref } from 'vue'
import { useFetch } from '#imports'
const count = ref(0)
const { data } = await useFetch('/api/videos')

# 查看 .nuxt 目录中生成的导入映射
ls .nuxt/imports.d.ts        # TypeScript 类型声明
ls .nuxt/components.d.ts     # 组件类型声明

// .nuxt/imports.d.ts（自动生成，不要手动修改）
export { ref, computed, watch, ... } from 'vue'
export { useFetch, useAsyncData, ... } from '#app/composables'
export { useAuth } from '/path/to/app/composables/useAuth'
export { formatDate } from '/path/to/app/utils/formatDate'

// 场景 1：在非 Nuxt 上下文中使用（如纯 .ts 工具文件）
import { useRuntimeConfig } from '#imports'
 
// 场景 2：需要区分同名导出
import { Button } from '#components'
 
// 场景 3：IDE 类型提示不工作时的 fallback
import type { NuxtApp } from '#app'

// nuxt.config.ts — 可以通过 imports 和 components 字段配置
export default defineNuxtConfig({
  // Composables / 工具函数自动导入配置
  imports: {
    dirs: ['composables', 'utils'],  // 默认扫描目录
  },
 
  // 组件自动导入配置
  components: {
    dirs: [
      { path: '~/components', pathPrefix: true },  // 默认
    ],
  },
})

{
  "extends": "./.nuxt/tsconfig.json"
}

// app/composables/useAuth.ts
export function useAuth() { ... }
 
// 某个第三方模块也导出了 useAuth
// → 冲突：哪个 useAuth？

// app/utils/ref.ts
export function ref() { ... }  // ❌ 与 Vue 的 ref 冲突

cat .nuxt/imports.d.ts | grep "useAuth"
# 查看 useAuth 的来源

// nuxt.config.ts
export default defineNuxtConfig({
  debug: true,  // 启用调试日志
  imports: {
    autoImport: true,
  },
})

// 方法 1：显式导入（覆盖自动导入）
import { useAuth } from '~/composables/useAuth'  // 明确指定来源
 
// 方法 2：在 nuxt.config 中排除冲突项
export default defineNuxtConfig({
  imports: {
    // 排除特定自动导入
    exclude: ['useAuth'],  // 不自动导入 useAuth，需要手动 import
  },
})
 
// 方法 3：组件重命名（pathPrefix）
export default defineNuxtConfig({
  components: {
    dirs: [
      { path: '~/components/ui', prefix: 'Ui' },
      { path: '~/components/form', prefix: 'Form' },
    ],
  },
})

// nuxt.config.ts
export default defineNuxtConfig({
  imports: {
    dirs: [
      'composables',     // 默认
      'utils',           // 默认
      'stores',          // 自定义：Pinia stores
      'helpers/**',      // 自定义：递归扫描 helpers
    ],
  },
})

// nuxt.config.ts
export default defineNuxtConfig({
  imports: {
    presets: [
      // 从 date-fns 自动导入常用函数
      {
        from: 'date-fns',
        imports: ['format', 'formatDistance', 'subDays', 'addDays'],
      },
      // 从 lodash-es 自动导入
      {
        from: 'lodash-es',
        imports: ['debounce', 'throttle', 'cloneDeep', 'groupBy'],
      },
    ],
  },
})

// 完全禁用（不推荐，但大型团队可能偏好显式导入）
export default defineNuxtConfig({
  imports: {
    autoImport: false,  // 禁用 Composables/工具函数自动导入
  },
  components: {
    dirs: [],  // 禁用组件自动导入
  },
})

// nuxt.config.ts
export default defineNuxtConfig({
  components: {
    dirs: [
      // 默认组件目录
      {
        path: '~/components',
        pathPrefix: true,       // 目录名作为前缀
        extensions: ['vue'],    // 只扫描 .vue 文件
      },
      // UI 组件库：不加目录前缀
      {
        path: '~/components/ui',
        prefix: '',             // 无前缀：Button.vue → <Button />
        pathPrefix: false,
      },
      // 全局组件：注册为全局（不做懒加载）
      {
        path: '~/components/global',
        global: true,
      },
    ],
  },
})

// nuxt.config.ts
export default defineNuxtConfig({
  imports: {
    dirs: [
      'composables',
      'utils',
      'stores',
    ],
    presets: [
      {
        from: 'date-fns',
        imports: ['format', 'formatDistanceToNow'],
      },
    ],
  },
  components: {
    dirs: [
      // 业务组件：带目录前缀
      { path: '~/components', pathPrefix: true },
      // UI 基础组件：无前缀
      { path: '~/components/ui', prefix: '', pathPrefix: false },
    ],
  },
})