Vue API实现自动导入

# Vue 3 开发利器：配置 API 自动导入（unplugin-auto-import）解放双手

在 Vue 3 项目开发中，我们几乎每天都要在每一个 `.vue` 或 `.ts` 文件头部重复书写如下代码：

```typescript
import { ref, reactive, computed, watch, onMounted } from 'vue'
import { useRouter, useRoute } from 'vue-router'
import { useStore } from 'pinia'

当项目越来越大时，这种手动引入 API 的操作不仅繁琐，还会让代码头部堆积大量模板化的 import 声明。

本文将介绍如何使用官方推荐的 unplugin-auto-import 插件实现 Vue 全局 API 自动按需引入，让你彻底告别手写 API 引入！

什么是 `unplugin-auto-import`？

unplugin-auto-import 是一款支持 Vite、Webpack、Rollup 等构建工具的自动导入插件。它可以在编译期自动解析你在代码中使用的 ref、reactive、computed 等函数，并在后台自动帮补全引用，无需手动配置全局变量，同时支持完美的 TypeScript 类型补全。

🛠️ 配置步骤

1. 安装依赖

在项目根目录下运行安装命令（以 pnpm 为例）：

pnpm add -D unplugin-auto-import

2. 配置 Vite (`vite.config.ts`)

修改项目根目录下的 vite.config.ts，导入插件并添加配置：

import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueJsx from '@vitejs/plugin-vue-jsx'
import AutoImport from 'unplugin-auto-import/vite'

export default defineConfig({
  plugins: [
    vue(),
    vueJsx(),
    // 配置自动导入插件
    AutoImport({
      // 指定需要自动导入 API 的库
      imports: [
        'vue',
        'vue-router',
        'pinia',
      ],
      // 自动在 src 目录下生成类型声明文件 auto-imports.d.ts
      dts: 'src/auto-imports.d.ts',
    }),
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
})

3. 配置 TypeScript 类型支持 (`tsconfig.app.json`)

为了避免 TypeScript 在未手动 import 时报错（提示 Cannot find name 'ref'），需要将插件生成的 auto-imports.d.ts 加入 TS 的 include 声明中。

修改 tsconfig.app.json（或 tsconfig.json）：

{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "include": [
    "env.d.ts",
    "src/**/*",
    "src/**/*.vue",
    "src/auto-imports.d.ts"
  ],
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

提示：配置完成后，启动一次开发服务（如 pnpm dev），插件就会在 src/ 目录下自动生成 auto-imports.d.ts 文件。

⚡ 效果对比

❌ 配置前

<script setup lang="ts">
import { ref, computed, onMounted } from 'vue'
import { useRoute } from 'vue-router'

const route = useRoute()
const count = ref(0)
const doubleCount = computed(() => count.value * 2)

onMounted(() => {
  console.log('Component mounted, current route:', route.path)
})
</script>

✅ 配置后

<script setup lang="ts">
// 干净利落，直接使用！
const route = useRoute()
const count = ref(0)
const doubleCount = computed(() => count.value * 2)

onMounted(() => {
  console.log('Component mounted, current route:', route.path)
})
</script>

💡 补充技巧：结合 ESLint（可选）

如果你在项目中使用 ESLint，可能会遇到 no-undef 规则报错。可以通过在 AutoImport 配置中开启 eslintrc 选项生成全局配置：

AutoImport({
  imports: ['vue', 'vue-router', 'pinia'],
  dts: 'src/auto-imports.d.ts',
  eslintrc: {
    enabled: true, // 首次运行生成 .eslintrc-auto-import.json 后可改为 false
  },
})

然后在 .eslintrc.cjs 中扩展引入该文件即可：

module.exports = {
  extends: [
    './.eslintrc-auto-import.json',
  ],
}

📝 总结

通过使用 unplugin-auto-import：

提升开发体验：不再需要时刻关注 API 是否引入。
保持代码精简：减少文件顶部模板化的导入行。
类型保障：与 TypeScript 完美结合，智能提示与类型检查不受影响。