Vite+Vue3 模块自动导入实战：彻底告别繁琐的 import 语句

如果你写过一段时间 Vue3 项目，一定对这样的代码场景不陌生：打开一个 .vue 文件，顶部的 import 语句占了快半屏，ref、reactive、useRouter、defineStore 这些高频 API 要反复手动引入，自定义组件也要挨个 import 注册，不仅代码冗余，重构时还容易漏改引入路径。

今天就来介绍 Vite+Vue3 项目中两个必备的自动导入插件：unplugin-auto-import 负责自动导入所有 JS API，unplugin-vue-components 负责自动导入所有组件，配置完成后你的代码可以干净到完全没有一行 import 语句。

一、API 自动导入：unplugin-auto-import

这个插件由 Vue 核心团队成员 Anthony Fu 开发，能在构建阶段自动识别你代码中使用的 Vue、VueRouter、Pinia、VueUse 等库的 API，按需注入对应的 import 语句，完全不影响生产包体积。

1. 基础安装与配置

首先安装插件：

arduino 复制代码

pnpm add -D unplugin-auto-import

然后在 vite.config.ts 中添加配置：

javascript 复制代码

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import AutoImport from 'unplugin-auto-import/vite'

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      // 开启 TypeScript 类型声明生成，解决 IDE 类型报错
      dts: 'src/types/auto-imports.d.ts',
      // 配置需要自动导入的库预设
      imports: [
        'vue',           // ref、reactive、computed、onMounted 等 Vue3 核心 API
        'vue-router',    // useRouter、useRoute 等路由 API
        'pinia',         // defineStore、storeToRefs 等 Pinia API
        '@vueuse/core'   // VueUse 工具函数库
      ],
      // 自动生成 ESLint 全局变量配置，解决 no-undef 报错
      eslintrc: {
        enabled: true,
        filepath: './.eslintrc-auto-import.json',
        globalsPropValue: true
      }
    })
  ]
})

配置完成后重启开发服务器，你就可以直接在代码里使用所有 API，无需任何 import：

scss 复制代码

<script setup lang="ts">
// 无需 import，直接使用
const count = ref(0)
const doubled = computed(() => count.value * 2)
const router = useRouter()
const route = useRoute()
const userStore = useUserStore()

onMounted(() => {
  console.log('组件已挂载')
})
</script>

2. 进阶用法

自定义模块导入：除了内置预设，你也可以配置自动导入自己的工具函数：

arduino 复制代码

imports: [
  'vue',
  {
    // 从自定义路径导入指定函数
    '@/utils/request': ['request', 'download'],
    // 导入默认导出并重命名
    'axios': 
  }
]

自动导入本地 hooks ：如果你把组合式函数放在 src/composables 目录下，可以直接配置 dirs 自动扫描导入：

bash 复制代码

AutoImport({
  dirs: ['src/composables/**'],
})

配置后 src/composables 目录下所有导出的函数都可以在组件中直接使用，无需手动 import。

二、组件自动导入：unplugin-vue-components

这个插件可以自动识别模板中使用的组件，按需注入对应的 import 和注册语句，支持项目自定义组件和主流 UI 库的按需加载。

1. 基础安装与配置

安装插件：

csharp 复制代码

pnpm add -D unplugin-vue-components

在 vite.config.ts 中添加配置：

javascript 复制代码

import Components from 'unplugin-vue-components/vite'

export default defineConfig({
  plugins: [
    Components({
      // 自动扫描的组件目录，默认就是 src/components
      dirs: ['src/components'],
      // 递归扫描子目录
      deep: true,
      // 生成组件类型声明文件
      dts: 'src/types/components.d.ts'
    })
  ]
})

配置完成后，你在 src/components 目录下创建的任何 .vue 组件，都可以直接在模板中使用，无需 import 注册：

xml 复制代码

<template>
  <!-- 直接使用，无需 import -->
  <MyButton @click="handleClick" />
  <UserCard :user="currentUser" />
</template>

插件会自动把组件名转换为 PascalCase 识别，比如 src/components/user-card/index.vue 对应的组件名就是 <UserCard />。

2. UI 库按需导入

如果你使用了 Element Plus、Ant Design Vue 等 UI 库，可以直接使用内置的 resolver 实现按需加载，连样式都会自动按需引入：

php 复制代码

import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'

Components({
  dirs: ['src/components'],
  resolvers: [ElementPlusResolver()]
})

配置后可以直接在模板里使用 Element Plus 组件，无需任何引入：

xml 复制代码

<template>
  <el-button type="primary" @click="handleClick">按钮</el-button>
  <el-input v-model="inputValue" />
</template>

三、配套配置：让开发体验更丝滑

1. TypeScript 类型支持

两个插件都会自动生成 .d.ts 类型声明文件，你需要确保 tsconfig.json 的 include 字段包含了这些文件：

json 复制代码

{
  "include": [
    "src/**/*.ts",
    "src/**/*.vue",
    "src/types/auto-imports.d.ts",
    "src/types/components.d.ts"
  ]
}

配置后 IDE 就能正常识别所有自动导入的 API 和组件，提供完整的类型提示。

2. ESLint 兼容

如果你使用了 ESLint，需要把插件生成的全局变量配置引入到你的 .eslintrc.cjs 中：

java 复制代码

module.exports = {
  extends: [
    // 引入自动导入的全局变量声明，解决 no-undef 报错
    './.eslintrc-auto-import.json'
  ]
}

3. 调试技巧

如果你想查看插件实际注入了哪些 import 语句，可以安装 vite-plugin-inspect 插件：

csharp 复制代码

pnpm add -D vite-plugin-inspect

配置后访问 http://localhost:5173/__inspect/，就可以查看每个文件编译后的实际内容，方便排查问题。

四、常见问题排查

Q1：IDE 没有类型提示，API 报红

检查 dts 配置是否开启，生成的 .d.ts 文件是否被 tsconfig.json 的 include 包含
重启 IDE 的 TypeScript 服务（VSCode 中按 Cmd+Shift+P 输入 TypeScript: Restart TS server）

Q2：ESLint 报 ref is not defined

确保 AutoImport 的 eslintrc.enabled 设置为 true，生成了 .eslintrc-auto-import.json 文件
确保你的 .eslintrc 配置中 extends 引入了这个文件

Q3：自定义组件自动导入不生效

检查组件路径是否在 dirs 配置的扫描范围内
确保组件文件名符合规范：ComponentName.vue 或 ComponentName/index.vue
删除自动生成的 components.d.ts 文件，重启开发服务器重新生成

Q4：自动生成的 .d.ts 文件要不要提交到 git？

建议加入 .gitignore，这些文件会在每次启动项目时自动生成，提交到 git 会导致频繁的无意义改动。

总结

配置这两个插件总共只需要 5 分钟，却能极大提升开发体验：代码更简洁，不用在思考业务逻辑和写机械的 import 语句之间频繁切换；维护更方便，重构时不需要检查 import 路径是否正确；团队协作更统一，所有人都遵循同一套自动导入规则。如果你的 Vue3 项目还没有配置自动导入，强烈建议现在就加上，用过就再也回不去了。